-
Notifications
You must be signed in to change notification settings - Fork 5
API 20141201 Program Response
Robert Kulagowski edited this page May 20, 2016
·
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.
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.
[Show | Episode | Sports | 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.
{
"programID": "EP012599310061",
"resourceID": "8100033",
"titles": [
{
"title120": "Hot in Cleveland"
}
],
"descriptions": {
"description100": [
{
"descriptionLanguage": "en",
"description": "Melanie's hair blow out lasts unusually long; tensions rise among the ladies."
}
],
"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."
}
]
},
"originalAirDate": "2012-06-06",
"genres": [
"Sitcom"
],
"episodeTitle150": "Blow Outs",
"metadata": [
{
"Gracenote": {
"season": 3,
"episode": 24,
"totalEpisodes": 24
}
}
],
"duration": 1320,
"cast": [
{
"billingOrder": "01",
"role": "Actor",
"nameId": "154",
"personId": "154",
"name": "Valerie Bertinelli",
"characterName": "Melanie Moretti"
},
{
"billingOrder": "02",
"role": "Actor",
"nameId": "1918",
"personId": "1918",
"name": "Betty White",
"characterName": "Elka Ostrovsky"
},
{
"billingOrder": "03",
"role": "Actor",
"nameId": "65675",
"personId": "65675",
"name": "Wendie Malick",
"characterName": "Victoria Chase"
},
{
"billingOrder": "04",
"role": "Actor",
"nameId": "71516",
"personId": "71516",
"name": "Jane Leeves",
"characterName": "Joy Scroggs"
},
{
"billingOrder": "05",
"role": "Guest Star",
"nameId": "639710",
"personId": "618197",
"name": "Elizabeth J. Carlisle",
"characterName": "Shamed Woman"
},
{
"billingOrder": "06",
"role": "Guest Star",
"nameId": "691245",
"personId": "664581",
"name": "Carol Herman",
"characterName": "Mrs. Magee"
},
{
"billingOrder": "07",
"role": "Guest Star",
"nameId": "1345",
"personId": "1345",
"name": "Regis Philbin",
"characterName": "Pierre"
},
{
"billingOrder": "08",
"role": "Guest Star",
"nameId": "15748",
"personId": "15748",
"name": "David Spade",
"characterName": "Christopher"
}
],
"entityType": "Episode",
"showType": "Series",
"hasImageArtwork": true,
"episodeImage": {
"width": "240",
"height": "360",
"uri": "assets/p9094920_e_v5_ab.jpg",
"category": "Iconic",
"primary": "true",
"tier": "Episode"
},
"md5": "k7AvJ/yw4P9shqMgw7YlbA"
}
This is the "SH" for the same series:
{
"programID": "SH012599310000",
"resourceID": "8100033",
"titles": [
{
"title120": "Hot in Cleveland"
}
],
"descriptions": {
"description100": [
{
"descriptionLanguage": "en",
"description": "Best friends rediscover themselves in Ohio."
}
],
"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)."
}
]
},
"originalAirDate": "2010-06-16",
"genres": [
"Sitcom"
],
"metadata": [
{
"Gracenote": {
"totalEpisodes": 153,
"totalSeasons": 6
}
}
],
"keyWords": {
"Mood": [
"Hilarious",
"Charming",
"Spirited"
],
"Time Period": [
"2010s"
],
"Character": [
"Middle-aged woman",
"Friend",
"Caretaker",
"Actress",
"Beautician",
"Neighbor"
],
"Setting": [
"Cleveland",
"House"
],
"Subject": [
"Midlife crisis",
"Relocation",
"Female bonding",
"Dating"
]
},
"contentRating": [
{
"body": "USA Parental Rating",
"code": "TVPG"
}
],
"cast": [
{
"billingOrder": "01",
"role": "Actor",
"nameId": "154",
"personId": "154",
"name": "Valerie Bertinelli",
"characterName": "Melanie Moretti"
},
{
"billingOrder": "02",
"role": "Actor",
"nameId": "1918",
"personId": "1918",
"name": "Betty White",
"characterName": "Elka Ostrovsky"
},
{
"billingOrder": "03",
"role": "Actor",
"nameId": "65675",
"personId": "65675",
"name": "Wendie Malick",
"characterName": "Victoria Chase"
},
{
"billingOrder": "04",
"role": "Actor",
"nameId": "71516",
"personId": "71516",
"name": "Jane Leeves",
"characterName": "Joy Scroggs"
}
],
"crew": [
{
"billingOrder": "01",
"role": "Executive Producer",
"nameId": "153066",
"personId": "86955",
"name": "Sean Hayes"
},
{
"billingOrder": "02",
"role": "Executive Producer",
"nameId": "646590",
"personId": "624973",
"name": "Todd Milliner"
}
],
"entityType": "Show",
"showType": "Series",
"recommendations": [
{
"programID": "SH007633980000",
"title120": "The New Adventures of Old Christine"
},
{
"programID": "SH011580820000",
"title120": "Cougar Town"
},
{
"programID": "SH014076210000",
"title120": "Happily Divorced"
}
],
"awards": [
{
"recipient": "Betty White",
"name": "Screen Actors Guild Awards",
"awardName": "Screen Actors Guild Awards",
"personId": "1918",
"year": "2011",
"category": "Outstanding Performance by an Ensemble in a Comedy Series"
},
{
"recipient": "Betty White",
"name": "Screen Actors Guild Awards",
"awardName": "Screen Actors Guild Awards",
"personId": "1918",
"won": true,
"year": "2011",
"category": "Outstanding Performance by a Female Actor in a Comedy Series"
},
{
"recipient": "Wendie Malick",
"name": "Screen Actors Guild Awards",
"awardName": "Screen Actors Guild Awards",
"personId": "65675",
"year": "2011",
"category": "Outstanding Performance by an Ensemble in a Comedy Series"
},
{
"recipient": "Valerie Bertinelli",
"name": "Screen Actors Guild Awards",
"awardName": "Screen Actors Guild Awards",
"personId": "154",
"year": "2011",
"category": "Outstanding Performance by an Ensemble in a Comedy Series"
},
{
"recipient": "Jane Leeves",
"name": "Screen Actors Guild Awards",
"awardName": "Screen Actors Guild Awards",
"personId": "71516",
"year": "2011",
"category": "Outstanding Performance by an Ensemble in a Comedy Series"
},
{
"recipient": "Betty White",
"name": "Emmy (Primetime)",
"awardName": "Emmy (Primetime)",
"personId": "1918",
"year": "2011",
"category": "Outstanding Supporting Actress in a Comedy Series"
},
{
"recipient": "Betty White",
"name": "Screen Actors Guild Awards",
"awardName": "Screen Actors Guild Awards",
"personId": "1918",
"won": true,
"year": "2012",
"category": "Outstanding Performance by a Female Actor in a Comedy Series"
},
{
"recipient": "Betty White",
"name": "Screen Actors Guild Awards",
"awardName": "Screen Actors Guild Awards",
"personId": "1918",
"year": "2013",
"category": "Outstanding Performance by a Female Actor in a Comedy Series"
}
],
"hasImageArtwork": true,
"md5": "NCI2s7FTCf3NY9Cbv1tpjg"
}
{
"programID": "MV000158920000",
"titles": [
{
"title120": "Raiders of the Lost Ark"
}
],
"descriptions": {
"description100": [
{
"descriptionLanguage": "en",
"description": "Indiana Jones (Harrison Ford) braves snakes and Nazis to find the biblical ark of the covenant."
}
],
"description1000": [
{
"descriptionLanguage": "en",
"description": "Renowned archeologist and expert in the occult, Dr. Indiana Jones, is hired by the U.S. Government to find the Ark of the Covenant, which is believed to still hold the ten commandments. Unfortunately, agents of Hitler 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."
}
]
},
"genres": [
"Adventure",
"Action"
],
"officialURL": "http://www.indianajones.com/",
"keyWords": {
"Mood": [
"Thrilling",
"Engaging",
"Charming"
],
"Time Period": [
"1930s"
],
"Theme": [
"Escape",
"Adventure",
"Pursuit",
"Quest"
],
"Character": [
"Archaeologist",
"Villain",
"Explorer",
"Love interest"
],
"Setting": [
"Desert",
"Airplane",
"Germany",
"Egypt",
"Jungle",
"Washington, D.C."
],
"Subject": [
"Exploration",
"Expedition",
"Nazism",
"Showdown"
],
"General": [
"Ark of the Covenant",
"Snakes"
]
},
"contentRating": [
{
"body": "British Board of Film Classification",
"code": "PG"
},
{
"body": "Alberta's Film Classification Board",
"code": "14A"
},
{
"body": "B.C. Film Classification Office",
"code": "PG"
},
{
"body": "Manitoba Film Classification Board",
"code": "14A"
},
{
"body": "Maritime Film Classification Board",
"code": "14"
},
{
"body": "Ontario Film Review Board",
"code": "PG"
},
{
"body": "Saskatchewan Film and Video Classification Board",
"code": "PG"
},
{
"body": "Departamento de Justiça, Classificação, Títulos e Qualificação",
"code": "L"
},
{
"body": "Freiwillige Selbstkontrolle der Filmwirtschaft",
"code": "12"
},
{
"body": "Mediakasvatus- ja kuvaohjelmayksikkö",
"code": "K12"
},
{
"body": "Motion Picture Association of America",
"code": "PG"
},
{
"body": "Film & Publication Board",
"code": "10"
}
],
"contentAdvisory": [
"Adult Language",
"Adult Situations",
"Violence"
],
"movie": {
"year": "1981",
"duration": 6900,
"qualityRating": [
{
"ratingsBody": "Gracenote",
"rating": "4",
"minRating": "1",
"maxRating": "4",
"increment": ".5"
}
]
},
"cast": [
{
"billingOrder": "01",
"role": "Actor",
"nameId": "25704",
"personId": "25704",
"name": "Harrison Ford",
"characterName": "Dr. Henry 'Indiana' Jones, Jr."
},
{
"billingOrder": "02",
"role": "Actor",
"nameId": "35610",
"personId": "35610",
"name": "Karen Allen",
"characterName": "Marion Ravenwood"
},
{
"billingOrder": "03",
"role": "Actor",
"nameId": "74672",
"personId": "74672",
"name": "Paul Freeman",
"characterName": "Rene Belloq"
},
{
"billingOrder": "04",
"role": "Actor",
"nameId": "170192",
"personId": "169111",
"name": "Wolf Kahler",
"characterName": "Dietrich"
},
{
"billingOrder": "05",
"role": "Actor",
"nameId": "85233",
"personId": "85233",
"name": "Ronald Lacey",
"characterName": "Toht"
},
{
"billingOrder": "06",
"role": "Actor",
"nameId": "67941",
"personId": "67941",
"name": "John Rhys-Davies",
"characterName": "Sallah"
},
{
"billingOrder": "07",
"role": "Actor",
"nameId": "83286",
"personId": "83286",
"name": "Denholm Elliott",
"characterName": "Marcus Brody"
},
{
"billingOrder": "08",
"role": "Actor",
"nameId": "151447",
"personId": "151352",
"name": "Anthony Higgins",
"characterName": "Gobler"
},
{
"billingOrder": "09",
"role": "Actor",
"nameId": "3584",
"personId": "3584",
"name": "Alfred Molina",
"characterName": "Sapito"
}
],
"crew": [
{
"billingOrder": "01",
"role": "Director",
"nameId": "1672",
"personId": "1672",
"name": "Steven Spielberg"
},
{
"billingOrder": "02",
"role": "Writer (Story)",
"nameId": "23344",
"personId": "23344",
"name": "George Lucas"
},
{
"billingOrder": "03",
"role": "Writer (Story)",
"nameId": "162726",
"personId": "162064",
"name": "Philip Kaufman"
},
{
"billingOrder": "04",
"role": "Writer",
"nameId": "884",
"personId": "884",
"name": "Lawrence Kasdan"
},
{
"billingOrder": "05",
"role": "Executive Producer",
"nameId": "473903",
"personId": "465028",
"name": "Howard G. Kazanjian"
},
{
"billingOrder": "06",
"role": "Executive Producer",
"nameId": "23344",
"personId": "23344",
"name": "George Lucas"
},
{
"billingOrder": "07",
"role": "Producer",
"nameId": "140145",
"personId": "140145",
"name": "Frank Marshall"
},
{
"billingOrder": "08",
"role": "Associate Producer",
"nameId": "446163",
"personId": "437288",
"name": "Robert Watts"
},
{
"billingOrder": "09",
"role": "Original Music",
"nameId": "533648",
"personId": "516972",
"name": "John Williams"
},
{
"billingOrder": "10",
"role": "Cinematographer",
"nameId": "473904",
"personId": "465029",
"name": "Douglas Slocombe"
},
{
"billingOrder": "11",
"role": "Film Editor",
"nameId": "726543",
"personId": "696907",
"name": "Michael Kahn"
},
{
"billingOrder": "12",
"role": "Film Editor",
"nameId": "23344",
"personId": "23344",
"name": "George Lucas"
},
{
"billingOrder": "13",
"role": "Film Editor",
"nameId": "1672",
"personId": "1672",
"name": "Steven Spielberg"
},
{
"billingOrder": "14",
"role": "Casting",
"nameId": "473905",
"personId": "465030",
"name": "Jane Feinberg"
},
{
"billingOrder": "15",
"role": "Casting",
"nameId": "473906",
"personId": "465031",
"name": "Mike Fenton"
},
{
"billingOrder": "16",
"role": "Casting",
"nameId": "431308",
"personId": "422433",
"name": "Mary Selway"
},
{
"billingOrder": "17",
"role": "Production Designer",
"nameId": "424533",
"personId": "415658",
"name": "Norman Reynolds"
},
{
"billingOrder": "18",
"role": "Art Direction",
"nameId": "454627",
"personId": "445752",
"name": "Leslie Dilley"
},
{
"billingOrder": "19",
"role": "Set Decoration",
"nameId": "262828",
"personId": "259262",
"name": "Michael Ford"
},
{
"billingOrder": "20",
"role": "Costume Designer",
"nameId": "473907",
"personId": "465032",
"name": "Deborah Nadoolman"
},
{
"billingOrder": "21",
"role": "Hair Stylist",
"nameId": "473908",
"personId": "465033",
"name": "Mike Lockey"
},
{
"billingOrder": "22",
"role": "Makeup Artist",
"nameId": "473909",
"personId": "465034",
"name": "Dickie Mills"
}
],
"showType": "Feature Film",
"recommendations": [
{
"programID": "MV001522590000",
"title120": "National Treasure"
},
{
"programID": "MV001078290000",
"title120": "Lara Croft: Tomb Raider"
},
{
"programID": "MV000747180000",
"title120": "The Mummy"
}
],
"hasImageArtwork": true,
"md5": "6ag49RYljx0b3VF6iEY1xw"
}
A Sports event; note that this is not a "SP" programID.
{
"programID": "EP005544683862",
"titles": [
{
"title120": "MLB Baseball"
}
],
"eventDetails": {
"venue100": "Busch Stadium",
"teams": [
{
"name": "St. Louis Cardinals",
"isHome": true
},
{
"name": "Chicago Cubs"
}
],
"gameDate": "2015-10-10"
},
"descriptions": {
"description1000": [
{
"descriptionLanguage": "en",
"description": "The Cubs, led by young sluggers Anthony Rizzo and Kris Bryant, visit Matt Carpenter and the Cardinals in Game 2 of the National League Division Series."
}
],
"description100": [
{
"descriptionLanguage": "en",
"description": "From Busch Stadium."
}
]
},
"genres": [
"Playoff sports",
"Baseball"
],
"episodeTitle150": "Chicago Cubs at St. Louis Cardinals",
"entityType": "Sports",
"showType": "Sports event",
"hasImageArtwork": true,
"md5": "FSMo+rHrKUc7460HLy5E3g"
}