Format of an API 20131021 program

Post Reply
rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Format of an API 20131021 program

Post by rkulagow » Fri Feb 07, 2014 12:40 pm

Code: Select all

{
    "programID": "MV000000130000",
    "titles": {
        "title120": "1941"
    },
    "eventDetails": {
        "subType": "Feature Film"
    },
    "descriptions": {
        "description100": [
            {
                "descriptionLanguage": "en",
                "description": "The Japanese attack on Pearl Harbor causes mass panic in California."
            }
        ],
        "description1000": [
            {
                "descriptionLanguage": "en",
                "description": "After Japan's attack on Pearl Harbor, residents of California descend into a wild panic, afraid that they might be the next target. Among them are Wild Bill Kelso (John Belushi), a crazed National Guard pilot; Sgt. Frank Tree (Dan Aykroyd), a patriotic, straight-laced tank crew commander; Ward Douglas (Ned Beatty), a civilian willing to help with the American war effort at any cost; and Maj. Gen. Joseph W. Stilwell (Robert Stack), who tries his hardest to maintain sanity amid the chaos."
            }
        ]
    },
    "genres": [
        "Comedy"
    ],
    "contentRating": [
        {
            "body": "Departamento de Justiça, Classificação, Títulos e Qualificação",
            "code": "12"
        },
        {
            "body": "Maritime Film Classification Board",
            "code": "14"
        },
        {
            "body": "British Board of Film Classification",
            "code": "PG"
        },
        {
            "body": "Motion Picture Association of America",
            "code": "PG"
        },
        {
            "body": "Ontario Film Review Board",
            "code": "14A"
        },
        {
            "body": "The Régie du cinéma",
            "code": "G"
        }
    ],
    "images": [
        {
            "uri": "https://s3.amazonaws.com/schedulesdirect-API20131021/assets/p13_p_v5_aa.jpg",
            "dimension": "w=240px|h=360px",
            "md5": "159164e260d91e01b617ef"
        }
    ],
    "contentAdvisory": [
        "Adult Language",
        "Adult Situations"
    ],
    "movie": {
        "year": "1979",
        "duration": 7080,
        "qualityRating": [
            {
                "ratingsBody": "TMS",
                "rating": "2.5",
                "minRating": "1",
                "maxRating": "4",
                "increment": ".5"
            }
        ]
    },
    "cast": [
        {
            "personId": "32538",
            "nameId": "32538",
            "name": "John Belushi",
            "role": "Actor",
            "characterName": "Captain Wild Bill Kelso",
            "billingOrder": "01"
        },
        {
            "personId": "76",
            "nameId": "76",
            "name": "Dan Aykroyd",
            "role": "Actor",
            "characterName": "Sgt. Frank Tree",
            "billingOrder": "02"
        },
        {
            "personId": "71755",
            "nameId": "71755",
            "name": "Lorraine Gary",
            "role": "Actor",
            "characterName": "Joan Douglas",
            "billingOrder": "03"
        },
        {
            "personId": "47868",
            "nameId": "47868",
            "name": "Ned Beatty",
            "role": "Actor",
            "characterName": "Ward Douglas",
            "billingOrder": "04"
        },
        {
            "personId": "73534",
            "nameId": "73534",
            "name": "Treat Williams",
            "role": "Actor",
            "characterName": "Corporal Chuck \"Stretch\" Sitarski",
            "billingOrder": "05"
        },
        {
            "personId": "47520",
            "nameId": "47520",
            "name": "Nancy Allen",
            "role": "Actor",
            "characterName": "Donna Stratton",
            "billingOrder": "06"
        },
        {
            "personId": "55564",
            "nameId": "55564",
            "name": "Robert Stack",
            "role": "Actor",
            "characterName": "Major General Joseph W. Stillwell",
            "billingOrder": "07"
        },
        {
            "personId": "73277",
            "nameId": "73277",
            "name": "Tim Matheson",
            "role": "Actor",
            "characterName": "Captain Loomis Birkhead",
            "billingOrder": "08"
        },
        {
            "personId": "486669",
            "nameId": "496815",
            "name": "Toshirô Mifune",
            "role": "Actor",
            "characterName": "Commander Akiro Mitamura",
            "billingOrder": "09"
        },
        {
            "personId": "77249",
            "nameId": "77249",
            "name": "Christopher Lee",
            "role": "Actor",
            "characterName": "Captain Wolfgang von Kleinschmidt",
            "billingOrder": "10"
        },
        {
            "personId": "77770",
            "nameId": "77770",
            "name": "Warren Oates",
            "role": "Actor",
            "characterName": "Colonel Madman Maddox",
            "billingOrder": "11"
        },
        {
            "personId": "264572",
            "nameId": "268148",
            "name": "Bobby Di Cicco",
            "role": "Actor",
            "characterName": "Wally Stephens",
            "billingOrder": "12"
        },
        {
            "personId": "16813",
            "nameId": "16813",
            "name": "Dianne Kay",
            "role": "Actor",
            "characterName": "Betty Douglas",
            "billingOrder": "13"
        },
        {
            "personId": "84632",
            "nameId": "84632",
            "name": "Murray Hamilton",
            "role": "Actor",
            "characterName": "Claude Crumm",
            "billingOrder": "14"
        },
        {
            "personId": "75812",
            "nameId": "75812",
            "name": "Slim Pickens",
            "role": "Actor",
            "characterName": "Hollis P. Wood",
            "billingOrder": "15"
        },
        {
            "personId": "73871",
            "nameId": "73871",
            "name": "Eddie Deezen",
            "role": "Actor",
            "characterName": "Herbie Kaziminsky",
            "billingOrder": "16"
        },
        {
            "personId": "269",
            "nameId": "269",
            "name": "John Candy",
            "role": "Actor",
            "characterName": "Private Foley",
            "billingOrder": "17"
        }
    ],
    "crew": [
        {
            "personId": "1672",
            "nameId": "1672",
            "name": "Steven Spielberg",
            "role": "Director",
            "billingOrder": "01"
        },
        {
            "personId": "1983",
            "nameId": "1983",
            "name": "Robert Zemeckis",
            "role": "Writer (Story)",
            "billingOrder": "02"
        },
        {
            "personId": "318961",
            "nameId": "327178",
            "name": "Bob Gale",
            "role": "Writer (Story)",
            "billingOrder": "03"
        },
        {
            "personId": "73304",
            "nameId": "73304",
            "name": "John Milius",
            "role": "Writer (Story)",
            "billingOrder": "04"
        },
        {
            "personId": "1983",
            "nameId": "1983",
            "name": "Robert Zemeckis",
            "role": "Writer",
            "billingOrder": "05"
        },
        {
            "personId": "318961",
            "nameId": "327178",
            "name": "Bob Gale",
            "role": "Writer",
            "billingOrder": "06"
        },
        {
            "personId": "363926",
            "nameId": "372801",
            "name": "Buzz Feitshans",
            "role": "Producer",
            "billingOrder": "07"
        },
        {
            "personId": "311258",
            "nameId": "317097",
            "name": "Janet Healy",
            "role": "Associate Producer",
            "billingOrder": "08"
        },
        {
            "personId": "696907",
            "nameId": "726543",
            "name": "Michael Kahn",
            "role": "Associate Producer",
            "billingOrder": "09"
        },
        {
            "personId": "73304",
            "nameId": "73304",
            "name": "John Milius",
            "role": "Executive Producer",
            "billingOrder": "10"
        },
        {
            "personId": "516972",
            "nameId": "533648",
            "name": "John Williams",
            "role": "Original Music",
            "billingOrder": "11"
        },
        {
            "personId": "221752",
            "nameId": "224282",
            "name": "William A. Fraker",
            "role": "Cinematographer",
            "billingOrder": "12"
        },
        {
            "personId": "696907",
            "nameId": "726543",
            "name": "Michael Kahn",
            "role": "Film Editor",
            "billingOrder": "13"
        },
        {
            "personId": "478332",
            "nameId": "487207",
            "name": "Sally Dennison",
            "role": "Casting",
            "billingOrder": "14"
        },
        {
            "personId": "478333",
            "nameId": "487208",
            "name": "Dean Edward Mitzner",
            "role": "Production Designer",
            "billingOrder": "15"
        },
        {
            "personId": "464481",
            "nameId": "473356",
            "name": "John P. Austin",
            "role": "Set Decoration",
            "billingOrder": "16"
        },
        {
            "personId": "465032",
            "nameId": "473907",
            "name": "Deborah Nadoolman",
            "role": "Costume Designer",
            "billingOrder": "17"
        }
    ],
    "showType": "Feature Film",
    "recommendations": [
        {
            "programID": "MV000019230000",
            "title120": "Catch-22"
        },
        {
            "programID": "MV001638870000",
            "title120": "It's a Mad, Mad, Mad, Mad World"
        },
        {
            "programID": "MV000029460000",
            "title120": "Dr. Strangelove Or: How I Learned to Stop Worrying and Love the Bomb"
        }
    ],
    "md5": "p/5J+WAzGWZbfzYRCeTa9g"
}
Each program consists of a JSON object with the following fields:
programID: mandatory. 14 characters.
titles: mandatory. An array of titleXXX/string pairs indicating the max length of the title and the title. Title lengths may be:
title120 - mandatory
title70, title40, title 20, title10, alternateTitle - optional

descriptions: optional. An array of descriptionXXXX / pairs.
descriptionLanguage - mandatory for each element.
description1000 - max length of description is 1000 characters
description255 - max length of description is 255 characters
description100 - max length of description is 100 characters
description60, description40, alternateDescription255, alternateDescription100

For example, a "description1000" may have two descriptions, one in "descriptionLanguage" - "fr" and another in "en".

originalAirDate - optional. YYYY-MM-DD of first airing

genres: optional. An array of genres.

episodeTitle150: optional. 150 character max title of this particular episode

metadata: optional. Array of source / season and episode pairs.

images: link to coverart. If the URI starts with "https" and points to S3 at Amazon, the client should download directly. If it doesn't, then access it from the REST server, which will then send a redirect to Amazon.

contentAdvisory: optional. An array of advisories, such as Language, Adult Language, Strong Sexual Content, etc.

contentRating: optional. An array of rating body/code pairs.

movie: an array of movie-specific information
year - optional. Release year
qualityRating - optional. An array of quality ratings.
ratingsBody: mandatory.
rating: mandatory.
minRating: optional.
maxRating: optional.
increment: optional.
duration - optional. Indicates the duration of the film (in seconds). This duration may not be the same as when aired, due to commercials, editing for time, etc.

showType: optional.

cast: optional. An array of strings containing the following information
personId: Optional. An integer used to look up this person for additional information. Future feature.
nameId: Optional. An integer used to look up this person for additional information. Not the same as personId if the person is married, has a name change, etc. Future feature.
name:
role:
billingOrder:

crew: optional An array of strings containing the following information
personId: same as above.
nameId: same as above.
name:
role:
billingOrder:

md5: MD5 hash of the object. Used to determine whether anything within the object has changed, indicating that the client should refresh.

recommendations: an array of programID/titles for similar content.

A sports event may contain an optional eventDetails field:

Code: Select all

{
    "programID": "SP002937580000",
    "titles": {
        "title120": "NBA Basketball"
    },
    "eventDetails": {
        "subType": "Sports event",
        "venue": "BMO Harris Bradley Center",
        "teams": [
            {
                "name": "Atlanta Hawks"
            },
            {
                "name": "Milwaukee Bucks",
                "isHome": true
            }
        ],
        "gameDate": "2014-04-16"
    },
    "genres": [
        "Basketball"
    ],
    "episodeTitle150": "Atlanta Hawks at Milwaukee Bucks",
    "images": [
        {
            "uri": "assets/p191276_b_h3_aa.jpg",
            "dimension": "w=360px|h=270px"
        }
    ],
    "showType": "Sports event",
    "md5": "0B7uny0/PQOTL2WB55X1Jw"
}

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: Format of an API 20131021 program

Post by rkulagow » Thu Feb 20, 2014 11:35 am

Update to indicate that nameId and personId are optional.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: Format of an API 20131021 program

Post by rkulagow » Tue Mar 18, 2014 10:44 am

Update to demonstrate new "description" array and sub-elements.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: Format of an API 20131021 program

Post by rkulagow » Tue Apr 08, 2014 11:04 am

Update to include an example that has more fields in use.

Update contentAdvisory and contentRating.

Update description for image.

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: Format of an API 20131021 program

Post by rkulagow » Wed Apr 16, 2014 10:36 am

Update JSON examples and wrap them in code blocks so that formatting is preserved.

Add details on "eventDetails" for sporting events.

tikinoullc
Posts: 7
Joined: Tue Oct 29, 2013 6:47 pm

Re: Format of an API 20131021 program

Post by tikinoullc » Sun Apr 27, 2014 5:35 pm

Hi,
I have tried to download the program images (all the uri I get are in the format assets/<imagename>.jpg
per the documentation in this post I then used a get (with the token header) to https://json.schedulesdirect.org/assets ... _v5_aa.jpg (one of the images in the program data)
but I keep getting 404
is the URL I am using wrong or is it not implemented yet?

Thanks

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: Format of an API 20131021 program

Post by rkulagow » Sun Apr 27, 2014 5:57 pm

tikinoullc wrote:Hi,
I have tried to download the program images (all the uri I get are in the format assets/<imagename>.jpg
per the documentation in this post I then used a get (with the token header) to https://json.schedulesdirect.org/assets ... _v5_aa.jpg (one of the images in the program data)
but I keep getting 404
is the URL I am using wrong or is it not implemented yet?

Thanks
Is that a direct cut-and-paste? You don't have the /20131021/ in there.

The first time that any user requests one of the images it will just say "assets/{whatever}.

On the next server sync, the URL will point to Amazon S3 directly.

tikinoullc
Posts: 7
Joined: Tue Oct 29, 2013 6:47 pm

Re: Format of an API 20131021 program

Post by tikinoullc » Mon Apr 28, 2014 10:12 am

My bad,
I omitted the 20131021, thanks for pointing it out !

rkulagow
SD Staff
Posts: 915
Joined: Tue Aug 14, 2007 3:15 pm

Re: Format of an API 20131021 program

Post by rkulagow » Tue May 13, 2014 12:46 pm

Updated example to include quality rating for movies.

Post Reply