Retrieving Images

There is a number of metadata elements which are available to the client.

If the program contains a boolean called "hasImageArtwork" and it is TRUE, this means that this particular program has artwork available, such as DVD coverart, stills from the program, title cards, etc.

{
    "programID": "EP003851900001",
    "titles": [
        {
            "title120": "Gilmore Girls"
        }
    ],
    "eventDetails": {
        "subType": "Series"
    },
    "descriptions": {
        "description100": [
            {
                "descriptionLanguage": "en",
                "description": "A woman (Lauren Graham) endeavors to raise a daughter (Alexis Bledel) on her own."
            }
        ],
        "description1000": [
            {
                "descriptionLanguage": "en",
                "description": "Lorelai must ask her estranged parents for financial help when her daughter, Rory, is accepted into a prestigious prep school."
            }
        ]
    },
    "originalAirDate": "2000-10-05",
    "genres": [
        "Drama",
        "Comedy"
    ],
    "episodeTitle150": "Pilot",
    "metadata": [
        {
            "Tribune": {
                "season": 1,
                "episode": 1
            }
        }
    ],
    "cast": [
        {
            "personId": "68293",
            "nameId": "68293",
            "name": "Lauren Graham",
            "role": "Actor",
            "billingOrder": "01"
        },
        
		<snip>
		
    ],
    "crew": [
        {
            "personId": "189517",
            "nameId": "191244",
            "name": "Amy Sherman-Palladino",
            "role": "Executive Producer",
            "billingOrder": "01"
        },
        
		<snip>
		
    ],
    "showType": "Series",
    "hasImageArtwork": true,
    "md5": "jrdBFyHSsdymy3NNBme2aQ"
}

##Retrieving JSON index based on programID.

The available image artwork index is retrieved by using the following URL:

POST https://json.schedulesdirect.org/20140530/metadata/programs/

Token: Not Required

The body of the message should contain the leftmost 10 characters of the programID:

["SH00712240", "EP00714290"]

Which will return an index of what content is available:

[{"uri":"assets/p282288_b_h3_aa.jpg","height":"270","width":"360","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_h5_aa.jpg","height":"135","width":"180","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_h6_aa.jpg","height":"540","width":"720","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_h9_aa.jpg","height":"1080","width":"1440","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_v2_aa.jpg","height":"180","width":"135","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_v3_aa.jpg","height":"360","width":"270","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_v4_aa.jpg","height":"720","width":"540","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_v5_aa.jpg","height":"360","width":"240","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_v6_aa.jpg","height":"180","width":"120","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_v7_aa.jpg","height":"720","width":"480","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_v8_aa.jpg","height":"1440","width":"960","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}},{"uri":"assets/p282288_b_v9_aa.jpg","height":"1440","width":"1080","primary":"true","category":"Banner","caption":{"content":"Rock","lang":"en"}}]
{"response":"ERROR","code":6000,"serverID":"20140530.1","message":"This request (EP00714290) is invalid.","datetime":"2014-10-03T18:29:20Z"}

Each element is JSON, but the entire response is not.

Note that the second response was actually an error.

You may batch up to 5000 elements in each request.

##Retrieving JSON index based on rootId.

The returned JSON may contain a "rootId". If it does, you may obtain information using:

https://json.schedulesdirect.org/20140530/metadata/programs/{rootId}

GET https://json.schedulesdirect.org/20140530/metadata/programs/33125

Token: Not Required

Which returns:

[
    {
        "uri": "movies/AllPhotos/35605/35605_aa.jpg",
        "height": "432",
        "width": "288",
        "primary": "true",
        "category": "Poster Art",
        "caption": {
            "content": "Poster Art",
            "lang": "en"
        }
    },
    {
        "uri": "movies/AllPhotos/35605/35605_aa_t.jpg",
        "height": "108",
        "width": "72",
        "primary": "true",
        "category": "Poster Art",
        "caption": {
            "content": "Poster Art",
            "lang": "en"
        }
    },
    {
        "uri": "assets/35605_ab.jpg",
        "height": "288",
        "width": "432",
        "category": "Scene Still",
        "caption": {
            "content": "Billy Bob Thornton and Tony Cox in Terry Zwigoff's BAD SANTA.",
            "lang": "en"
        }
    },
	<snip>

##Retrieving an image

To retrieve a particular image, use the URI from the JSON index.

https://json.schedulesdirect.org/20140530/image/{uri}

So:

GET https://json.schedulesdirect.org/20140530/image/assets/p184655_b_h3_aa.jpg

This will send your client a 303 redirect which it must follow in order to retrieve the actual image:

https://s3.amazonaws.com/schedulesdirect-API20140530/assets/p184655_b_h3_aa.jpg

NOTE: If the URI is already "complete" and contains the S3 URL, then your client should access S3 directly.

##Retrieving images for a particular celebrity.

The program object also contains nameId and personId elements in the cast and crew section. The actor Lauren Graham has a personId of 68293, so

GET https://json.schedulesdirect.org/20140530/metadata/celebrity/68293

Token: Not Required

Returns

[
    {
        "uri": "assets/35605_aq.jpg",
        "height": "288",
        "width": "432",
        "category": "Scene Still",
        "caption": {
            "content": "Billy Bob Thornton and Lauren Graham in Terry Zwigoff's BAD SANTA.",
            "lang": "en"
        },
        "rootId": "33125",
        "title": "Bad Santa"
    },
    
	<snip>
	
    }

NOTE: personID is preferred, and always refers to a particular person. A person may have multiple names, due to marriage/divorce, or alternate spellings: "Ed" vs. "Edward" could have two different nameIDs, but would reference the same personID.

Your grabber may use the same /image/ call with the URI to retrieve that image:

https://json.schedulesdirect.org/20140530/image/{uri}

https://json.schedulesdirect.org/20140530/image/assets/35605_aq.jpg