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.

NOTE: "hasImageArtwork" is end-of-life as of API-20141201. It will not be included in the next API and is replaced with more-specific booleans, which are now included in the JSON response for forward-compatibility.

If the program contains a boolean called "hasSeriesArtwork" and it is TRUE, this means that this series has "SH" artwork available, and can be accessed using that record. In the example below, the "SH" record for Gilmore Girls is "SH003851900000"

If the program contains a boolean called "hasEpisodeArtwork" and it is TRUE, this means that this episode has artwork available, (which may have specific stills from the episode, or guest stars, etc).

{
    "resourceID": "184655",
    "programID": "EP003851900001",
    "titles": [
        {
            "title120": "Gilmore Girls"
        }
    ],
    "descriptions": {
        "description100": [
            {
                "descriptionLanguage": "en",
                "description": "Estranged from her family, a woman endeavors to raise a daughter on her own."
            }
        ],
 
<snip>
        {
            "billingOrder": "04",
            "role": "Writer",
            "nameId": "191244",
            "personId": "189517",
            "name": "Amy Sherman-Palladino"
        }
    ],
    "entityType": "Episode",
    "showType": "Series",
    "hasImageArtwork": true,
    "hasSeriesArtwork": true,
    "hasEpisodeArtwork": true,
    "md5": "EokeXZC4B7C8eXhrWqfgGA"
}

Following the same pattern, movies will contain "hasMovieArtwork":

{
    "programID": "MV000000010000",
    "titles": [
        {
            "title120": "Second-Hand Hearts"
        }
    ],

<snip>

 ],
    "entityType": "Movie",
    "showType": "Feature Film",
    "hasImageArtwork": true,
    "hasMovieArtwork": true,
    "md5": "/U2OwwvIIjvnX86Y8IgJpA"
}

and sports will contain "hasSportsArtwork":

{
    "resourceID": "191261",
    "programID": "SP002698290000",
    "titles": [
        {
            "title120": "College Football"
        }

<snip>

    "episodeTitle150": "Baylor at Texas",
    "entityType": "Sports",
    "showType": "Sports event",
    "hasImageArtwork": true,
    "hasSportsArtwork": true,
    "md5": "ALBclKTxKbQIuBuE6ccauw"
}

Retrieving JSON index based on programID.

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

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

- or -

GET https://json.schedulesdirect.org/20141201/metadata/programs/{programID}

Token: Not Required

If you wish to retrieve multiple indexes, use the POST endpoint.

For backwards compatibility, you may either send the leftmost 10 characters of the programID:

["SH00712240", "EP00714290"]

or the full 14 characters.

NOTE: 10-character programIDs for images is end-of-life as of API-20141201. The next API will require a 14-character programID for images.

The response from the API will return an index of what content is available.

If you send the leftmost 10 for an EP type, you will receive the SH program artwork because the server won't know which episode image artwork to reply with.

NOTE: to receive specific artwork for "hasEpisodeArtwork", "hasMovieArtwork" or "hasSportsArtwork", you must send the full 14 character programID.

[{"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/20141201/metadata/programs/{rootId}

GET https://json.schedulesdirect.org/20141201/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/20141201/image/{uri}

So:

GET https://json.schedulesdirect.org/20141201/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.

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