-
Notifications
You must be signed in to change notification settings - Fork 5
API 20141201 Program Response
Robert Kulagowski edited this page Oct 8, 2015
·
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: "Tribune"
- value: array consisting of:
- season: string indicating the season number. Mandatory.
- episode: string indicating the episode number. 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.
- 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.
md5: md5 hash value of the JSON. Mandatory.
{
"programID": "EP000000260111",
"titles": [
{
"title120": "227"
}
],
"descriptions": {
"description100": [
{
"descriptionLanguage": "en",
"description": "Mary witnesses the infidelity of Rose's boyfriend while on a trip to Atlantic City."
}
],
"description1000": [
{
"descriptionLanguage": "en",
"description": "Mary witnesses the infidelity of Rose's boyfriend (Kevin Peter Hall) while on a trip to Atlantic City."
}
]
},
"originalAirDate": "1990-02-03",
"genres": [
"Sitcom"
],
"episodeTitle150": "Do Not Pass Go",
"metadata": [
{
"Gracenote": {
"season": 5,
"episode": 18
}
}
],
"contentRating": [
{
"body": "USA Parental Rating",
"code": "TVG"
}
],
"cast": [
{
"billingOrder": "01",
"role": "Actor",
"nameId": "72873",
"personId": "72873",
"name": "Marla Gibbs"
},
{
"billingOrder": "02",
"role": "Actor",
"nameId": "192173",
"personId": "190403",
"name": "Hal Williams"
},
{
"billingOrder": "03",
"role": "Actor",
"nameId": "154807",
"personId": "154630",
"name": "Alaina Reed-Hall"
},
{
"billingOrder": "04",
"role": "Actor",
"nameId": "546796",
"personId": "153546",
"name": "Jackée Harry"
},
{
"billingOrder": "05",
"role": "Actor",
"nameId": "53538",
"personId": "53538",
"name": "Regina King"
},
{
"billingOrder": "06",
"role": "Actor",
"nameId": "104016",
"personId": "104016",
"name": "Helen Martin"
},
{
"billingOrder": "07",
"role": "Actor",
"nameId": "347015",
"personId": "338141",
"name": "Curtis Baldwin"
},
{
"billingOrder": "08",
"role": "Actor",
"nameId": "231167",
"personId": "228162",
"name": "Toukie Smith"
},
{
"billingOrder": "09",
"role": "Actor",
"nameId": "50723",
"personId": "50723",
"name": "Paul Winfield"
},
{
"billingOrder": "10",
"role": "Actor",
"nameId": "77420",
"personId": "77420",
"name": "Stoney Jackson"
},
{
"billingOrder": "11",
"role": "Actor",
"nameId": "7314",
"personId": "7314",
"name": "Barry Sobel"
},
{
"billingOrder": "12",
"role": "Guest Star",
"nameId": "80219",
"personId": "80219",
"name": "Earl Boen"
},
{
"billingOrder": "13",
"role": "Guest Star",
"nameId": "379848",
"personId": "370973",
"name": "Cyndi James Gossett"
},
{
"billingOrder": "14",
"role": "Guest Star",
"nameId": "716",
"personId": "716",
"name": "Kevin Peter Hall"
},
{
"billingOrder": "15",
"role": "Guest Star",
"nameId": "406389",
"personId": "397514",
"name": "Farrell Mayer"
},
{
"billingOrder": "16",
"role": "Guest Star",
"nameId": "1840",
"personId": "1840",
"name": "Luther Vandross"
},
{
"billingOrder": "17",
"role": "Guest Star",
"nameId": "446311",
"personId": "437436",
"name": "Thomas Nelson Webb"
}
],
"entityType": "Episode",
"showType": "Series",
"hasImageArtwork": true,
"md5": "2r4b3RA1xq4iK4NNF3GOAg"
}
{
"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"
}