Using IHS to get images

This section explains how to use the Image Handler Service (IHS) to get images.

IHS has been superseded by ImageService. You are recommended to use ImageService instead of IHS. See Working with images.

This section is retained as a reference for customers that are still using IHS.

The client UI application usually needs to retrieve images to represent content in the UI. The Image Handler Service (IHS) exposes APIs that enable it to do this.

When the application retrieves content metadata from the Metadata Service (MDS) (for example, when browsing live or  VOD content or searching) the metadata it receives includes references to various entities (series, programmes, and so on). It may also include one or more image URLs.

If it receives URLs, the client app can:

• Select the most appropriate image and use the URL to request in from IHS (by appending the URL to the base (<host>:<port>) URL.
  In this case, IHS redirects the request to Gracenote (or other third-party provider).
  With this option, it is not possible to crop or resize the images.
• Use one of these references to request the image from IHS. 
  With this option, the application can request the most suitable image at the dimensions that it requires from the IHS image store.

If using a URL supplied by MDS, note that the name of the key in the metadata from MDS includes the image's width and height. They key name takes this form:

Img_event_<width>_<height>_<content_type>_<image_type>

Valid content types and image types

Valid content_types and image_types are:

• content_type is one of the following:
  • episode
  • movie
  • season
  • series
  • shows
• image_type is one of the following:
  • Banner-L1
  • Banner-L2
  • Banner-L3
  • Banner-LO
  • Staple
  • with_text
  • with_text_Banner-L1
  • with_text_Banner-L2
  • with_text_Banner-L3
  • with_text_Banner-LO
  • with_text_Staple

Examples:

Img_event_270_400_shows

Img_event_270_360_movie_with_text_Banner-L1

If the request is not for a Gracenote (or third party) sourced image, IHS responds to the request by:

• Choosing the most appropriate image (according to the requested category (if any), whether the image contains text or not, and the requested size – it chooses the next largest image to the requested size, unless the largest image is smaller than the requested size, in which case, IHS upscales the image). If it cannot find a matching image in its local store, IHS:
  • Requests a set of images from Gracenote.
  • If Gracenote cannot supply any matching images, it selects a default image, matching genre if possible (using the content's genre from metadata from CPM, if available), and matching it to the genre specified in the default images.
  • If it cannot match the genre, it randomly selects an image from the full set of default images.
• Resizing and/or cropping the requested image to the required dimensions.
• Saving the resulting image file to an S3 bucket.
• Returning a Cloudfront URL to the client application.

IHS can work with any cloud CDN, as long as its supports HTTP upload.

Use cases

IHS supports the following use cases:

See also

For an overview of image (and other) metadata ingest, see  Image ingest.