Accessing Images through the API
The API supports a rich viewing experience by including multiple images for programs, series, contributors etc.
The images are made available for download via a CDN. An API document for a program, series or contributor will include an
images array, containing one object for each image related to the relevant program, series etc. Each object has a
url property containing a full URL from which the image can be downloaded (by HTTP GET). No additional permissions are required to download the images.
"images": [
{
"orientation": "landscape",
"imageId": "270191158",
"shape": "L5",
"hierarchyLevel": "series",
"mediaType": "image/jpg",
"aspectRatio": "16:9",
"source": "BBC Worldwide",
"depicts": {
"en": "API Cast Group - Catherine Tate, David Walliams"
},
"type": "series",
"url": "http://cdn.ecdapi.net/cdp-images/brand-78c553f2b4b965250d688ff21b5f15acd6472dea.ip1920x1080.jpg",
"subTypeShortCode": "CRCG",
"fileSize": 375464,
"width": 1920,
"height": 1080
}
]
Image Metadata
The images objects have many properties to help a client decide which image to use in a specific situation. The width, height, aspect ratio, media type etc. of the image are explicitly provided. Additional properties include:
- shape: This is Simply.TV’s code for the physical properties of the image. Typically the value is a code for the dimensions of the image, e.g. P1 for a small portrait image and L5 for a large landscape image. Click here to open a document containing a table of the standard shape values and their meanings . If Simply.TV’s contract with the customer includes special image treatment, bespoke shape values will be used to indicate that.
- subTypeShortCode: This is Simply.TV’s code for the nature of the image content. For example, CRHS indicates that the image is a “Contributor Head Shot,” i.e. an image of an actor, director etc., not in character, including his/her head and shoulders only.
Click here to open a document containing a full list of the different short codes and their meanings. - hierarchyLevel: As explained here, program documents and event documents also include the images associated with the program’s parent season and grandparent series. This property indicates which level of the hierarchy the image is specific to.
Selecting the Most Specific Program Image
Depending on the range of images that a content provider has made available to Simply.TV, a program document or an event document about an episode of a series may include any or all of the following images in any given size and shape:
- An image specific to the episode’s content.
- An image specific to the parent season.
- An image specific to the grandparent series.
- An image specific to the genre of the episode.
- Images that are specific to various contributors to the program.
Even if the content provider has made no images available, Simply.TV will still provide an image specific to the genre of the program.
The season and series images will be indicated by the hierarchyLevel property. The genre image will be indicated by a subTypeShortCode value of
PRGN.
Hence, if a client wishes to select the image from the above set that is most specific to the program, it should:
- Look for an image with a hierarchyLevel of program and a subTypeShortCode that is not PRGN.
- If one is not available, look for an image with a hierarchyLevel of season.
- If one is not available, look for an image with a hierarchyLevel of series.
- If one is not available, look for an image with a hierarchyLevel of program and a subTypeShortCode of PRGN.
