Custom Content Feed Specifications

Owned by Jason Diamond (Unlicensed)
Last updated: Nov 14, 2019 by Joel SpitalnikVersion comment
3 min read

Overview: This document goes through what data IRIS.TV recommends a client send for asset metadata. It also covers details on feed formatting. 

Asset Metadata

Metadata Field Requirements

Below is an example of metadata fields from a standard feed. Following that is a breakdown of what fields are Required, Preferred, and Optional. Optional fields should be included in the feed in the client has access to them in their CMS. 

id/GUID
title/name
description (shortdescription optional)
creationDate
publishedDate
lastModifiedDate
deletedDate
startDate
endDate
keywords/tags [separately"categories"ifpossible]
thumbnailURL
length (duration)
SourceURL/Content URL

Required

  • "id/GUID": (unique numeric identifier of asset)
  • "title/name": Video asset title
  • "publishedDate": The date/time when the video record was first published on your web site.
  • "lastModifiedDate": The date/time when the video record was last modified


Preferred

  • "keywords/tags": Keywords or tags associated with the video asset. Categories can be used for IRIS.TV to create a hierachical taxonomy
  • "thumbnailURL": URL to a thumbnail or image that you want to represent your video. For best results, image should be at least 300 pixels (width) with a 16:9 ratio.
  • "length": The duration of the video in milliseconds
  • "itemState": ACTIVE - asset is available for recommendation with IRIS.TV // INACTIVE - asset is not available for recommendation with IRIS.TV
  • "SourceURL": Media content source URL
  • "description": Video asset description


Optional

  • "startDate": The Availability start date. If null/omitted then the publishedDate will be used.
  • "endDate": The Availability end date. If omitted, then recency business rules will be used for content expiration.
  • "creationDate": The date/time when the video record was published. 


Note: If possible, all date formats should follow the UNIX Epoch time format in milliseconds.

Sample Asset from Client

{
  "id": 5331690110001,
  "name": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
  "shortDescription": "Donec congue orci vel ante posuere consectetur. Vestibulum vel eros velit. In suscipit arcu nec lectus posuere sagittis.",
  "creationDate": 1487717574502,
  "publishedDate": 1487717955852,
  "lastModifiedDate": 1487717955969,
  "startDate": 1487717955969,
  "endDate": null,
  "tags": [
    "alex rodriguez",
    "new york yankees",
    "mlb"
  ],
  "videoStillURL": "http://xxx/2157889318001_5331738223001_5331690110001-vs.jpg?pubId=2157889318001",
  "thumbnailURL": "http://xxx/2157889318001_5331738224001_5331690110001-th.jpg?pubId=2157889318001",
  "length": 30805,
  "economics": "AD_SUPPORTED",
  "categories": [
    "Baseball"
  ],
  "itemState": "ACTIVE",
  "SourceURL": "http://xxx/2157889318001_5331740038001_5331690110001.mp4"
},

For clarification, please find the definitions and/more information about the above feed fields below.

  • "id": GUID (unique numeric identifier of asset)
  • "name": Video asset title
  • "shortDescription": Video asset description
  • "creationDate": The date/time when the video record was published. 
  • "publishedDate": The date/time when the video record was first published on your web site.
  • "lastModifiedDate": The date/time when the video record was last modified
  • "startDate": The Availability start date. If null/omitted then the publishedDate will be used.
  • "endDate": The Availability end date. If omitted, then recency business rules will be used for content expiration.
  • "tags": Terms associated with video asset
  • "videoStillURL": URL to an image (optional)
  • "thumbnailURL": URL to a thumbnail or image that you want to represent your video. For best results, image should be at least 300 pixels (width) and 16:9 ratio.
  • "length": The duration of the video in milliseconds
  • "economics": "AD_SUPPORTED" if the content is monetized with pre-roll advertising
  • "categories": categories associated with the video, as an array of strings
  • "itemState": ACTIVE - asset is available for recommendation with IRIS.TV // INACTIVE - asset is not available for recommendation with IRIS.TV
  • "SourceURL": Media content source url


Feed Format

Supported Types 

IRIS.TV supports feeds formatted as XML or JSON. If the client has an API, they can provide an API route for IRIS.TV to evaluate for import. 

Supported Pagination

IRIS.TV prefers that clients use pagination for asset feeds. This allows IRIS.TV to import the client's full library instead of a set of most recent assets. IRIS.TV supports the following pagination methods:

  • Offset parameter: Feed parameters that allow for calling a specific number of assets and an offset for how far to go into the feed.
  • Next Link pagination: link for next page is included in the current page.

Recommended Ordering

IRIS.TV recommends that feeds are ordered by an "updated_at" field on the assets. That ensures that all asset updates are imported into the recommendation system.

IRIS.TV