Category Recommendation API

The following describes how to set up channel or carousel-based video recommendations via the following API route

Features:

1. Ability to request recommendations from specific categories that can be used to populate a carousel or build a channel
2. Ability for client to send thumbs_up and thumbs_down user interaction updates on videos before an initial video starts
3. Ability for client to send in a Watch call once a user starts watching a recommended video

Category /watch API Call Query:

A Category /watch Call should be made to request recommendations from a specific category ID.

Parameters - /watch API Call Request:

• category_id:required [STRING] The BSON ID for the category provided by IRIS.TV.

• platform: required [STRING] The name of the publisher

• number: required [INTEGER] The number of recommendations to be returned in the response (max 40)

• access_token: required [STRING] Token created via OAuth 2 standard

• user_id: required [STRING] A unique ID generated to be associated to the individual user

• client_token: required [STRING] Authentication string associated with each region

• recs_only: required [BOOLEAN] Set to true

Sample /watch API Call Request:

curl http://api.iris.tv/watch? \
    category_id=5876c42613a20c0ee9000010 \
    &platform=FP \ 
    &number=30 \ 
    &access_token=1d9f05c8b00daddfbffcf5afa8a0691bf6370c0cd9dfc8bc6fb38e13c4474dab \ 
    &user_id=BTORW \ 
    &client_token=JLAJ879fkh

Sample /watch API Call Response:

{
'success': true,
'next': [
{
'iris_id': '2140j908',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_1.mp4',
'platform_id': '241YOFG',
'title': 'Birdman International Trailer',
'release_date': '2014-08-01 18:34:33 UTC'
},
{
'iris_id': '51084789cd5f272312231105',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_2.mp4',
'platform_id': '343YOW',
'title': 'Snow Owl Short Film',
'release_date': '2012-10-22 12:30:58 UTC',
'reviewed': '2013-02-05 23:02:24 UTC',
},
{
'iris_id': '539a5ba7f09c3f00172310bb',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_3.mp4',
'platform_id': '780YOTSDB'',
'title': 'Blue Heron Teaser Trailer',
'release_date': '2014-06-12 20:51:53 UTC'
},
{
'iris_id': '53cdc6233459980016231012',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_4.mp4',
'platform_id': '9019YOPW',
'title': 'Penguin Clip',
'release_date': '2014-07-20 19:51:07 UTC'
},
{
'iris_id': '51084760cd5f2723122310a1',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_5.mp4',
'platform_id': '89YWQMD',
'title': 'Life & Times Trailer',
'release_date': '2012-11-30 05:48:51 UTC',
'reviewed': '2013-09-06 22:35:10 UTC',
},
{
'iris_id': '53814f1af1585f0032231014',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_6.mp4',
'platform_id': '46YDPA',
'title': 'Paleo Diet International Trailer',
'release_date': '2014-05-24 19:33:28 UTC'
}
],
'experience': '53ebec0d321d0690858dw5r1'
}

Response - /watch API Call Request:

• next: [ARRAY] Recommended assets based on the specified category. See below for asset fields.
• experience: Unique identifier for the current stream of videos. This value can be ignored.

Video Asset fields:

• iris_id: [STRING] IRIS.TV’s Reference ID for video

• platform: [STRING] the name of the publisher

• content_URL: [STRING] Link to video file on publisher’s CMS (only available if sent in during import process)

platform_id: [STRING] the Reference ID from the publisher’s CMS

• title: [STRING] Title of video via publisher’s CMS

release_date: [STRING] Date when asset could be recommended (UTC)

• reviewed: [STRING] Date when asset was reviewed by IRIS.TV staff (UTC)
• experience: [STRING] Unique identifier for the current stream of videos. Note: a new experience is generated on every watch call.

Error Notifications:

Invalid Access Token

Status Code: 401 Unauthorized IRIS.TV Response: “The access token is no longer valid” Problem: Access Token is invalid or has expired Solution: Create a new access token using OAuth 2

[Documentation for creating access tokens]

Invalid Client Token

Status Code: 401 Unauthorized IRIS.TV Response: “IRIS API: Check your authentication credentials” Problem: Client Token is Incorrect Solution: Double check your client token. If still invalid, contact IRIS.TV support.

No Assets in Next Field

Problem: No assets in library. Solution: Contact IRIS.TV representative and check import schedule.