Video Recommendation APIs
      Back to home
      1. Knowledge Base and Documentation
      2. Video Recommendations
      3. Video Recommendation APIs

      Video Player Personalization APIs

      IRIS.TV's API can be used to generate recommendations in continuous play and static display envirnoments

      The API has three main calls:

      1. Watch
      2. Update
      3. Next

      The Watch Call is made when a viewing experience is initiated. This can either happen when a user clicks on an asset or the first video is played. This call generates a list of recommendations as well as an Experience value, which is used to track all user behavior in the video stream.

      The Update Call is made to send any information on viewer behavior to IRIS.TV. These behaviors include: Play, Video Complete, Skip, Pause, Thumbs Up, Thumbs Down.

      The Next Call is made to refresh or extend the viewing experience. This should be made in three situations: (1) if a viewer reaches the end of the videos made on the Watch call; (2) if a viewer clicks Thumbs Up on a video; (3) if a viewer clicks Thumbs Down on a video.

      All IRIS.TV API calls require an access token created using the OAuth 2 standard.

      Watch Call

      A Watch Call should be made whenever a viewing experience is initiated. This can happen when a viewer clicks on an asset or when the first video is auto-played.

      The necessary parameters for a watch call are:

      platform_id: The reference ID from the publisher’s CMS
      platform: The name of the publisher
      number: The number of recommendations to be returned in the response
      access_token: Token created via OAuth 2 standard
      user_id: A unique ID generated to be associated to the individual user
      client_token: Authentication string associated with each client
      recs_only: Set to `true`. [If `false` then the Watch call will also indicate the start of play of the initial video.] 

      Please reference the Parameter Glossary for more information on these parameters.

      Sample Workflow

      Client is requesting five assets in a call, for User BTORW.

      Documentation for creating access tokens

      SSL:

      The API supports both standard HTTP and HTTPS calls with SSL/TLS encryption.

      Call:

      https://api.iris.tv/watch?platform_id=241YOFG&platform=videopublisher&number=5&access_token=996JVD321AZ&user_id=BTORW&recs_only=true&client_token=99999

      Response:

      jQuery191028397097534104254_1407970311998({
      'success': true,
      'next': [
      {
      'iris_id': '2140j908',
      'platform': 'VideoPublisher',
      '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': 'VideoPublisher',
      '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'
      },
      {
      'iris_id': '539a5ba7f09c3f00172310bb',
      'platform': 'VideoPublisher',
      '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': 'VideoPublisher',
      'content_url': 'http://www.credenza.com/asset_4.mp4',
      'platform_id': '9019YOPW',
      'title': 'Nelson Simcoe Clip',
      'release_date': '2014-07-20 19:51:07 UTC'
      },
      {
      'iris_id': '51084760cd5f2723122310a1',
      'platform': 'VideoPublisher',
      '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'
      },
      {
      'iris_id': '53814f1af1585f0032231014',
      'platform': 'VideoPublisher',
      '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',
      'sc':false
      })

      The “Next” field will contain an echo of the asset passed on the Watch call as the first video. After the echoed asset, the requested number of assets will be displayed.

      After the list of assets is the “experience” value. The experience will be passed on all Update and Next calls that follow the Watch call.

      Video Parameters In Watch Response:

      iris_id: IRIS.TV’s Reference ID for video
      platform: the name of the publisher
      content_URL: Link to video file on publisher’s CMS (only available if sent in during import process)
      platform_id: the Reference ID from the publisher’s CMS
      title: Title of video via publisher’s CMS
      release_date: Date when asset could be recommended
      reviewed: Date when asset was reviewed by IRIS.TV staff
      experience: Value that defines the current stream of videos. Note: a new experience is generated on every watch call.
      sc: Boolean value that indicates whether or not a cookie has been set.
      default_recs:       Notifies if recommendations are not based on the current asset. Only appears if set to “true.” Occurs when asset passed through in the Watch Call is unknown

       

      If default_recs=true, then the API response will NOT include the initial asset. The response will ONLY include the requested recommendations.

       

      Errors

      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.

      Update Call

      After the experience has been started with the Watch call, the Update call is used to send any user interaction to the IRIS.TV API.

      Necessary Parameters for an Update Call:

      platform_id: the reference ID from the publisher’s CMS
      platform: the name of the publisher
      experience: Value that defines current stream of videos (generated on Watch call)
      access_token: created via OAuth 2 standard
      user_id: ID associated to the individual user
      client_token: string of characters to authorize the client
      behavior: field that covers any user behaviors. Note: multiple behaviors can be included in one Update call

      List of Standard Behavior Parameters:

      behavior[play]:Video Starts Playing (Value 1)
      behavior[video_complete]:Video Complete (Value 1)
      behavior[pause]:Video Paused (Value 1)
      behavior[next]:Video Skipped/Next (Value 1)
      behavior[next_auto]:Next Video Played in Autoplay Mode(Value 1)
      behavior[thumbs_up]:User clicked liked (Value 1)
      behavior[thumbs_down]:User clicked disliked (Value 1)
      behavior[percentage_watched]:Percentage Video Watched (Value 0.0 -­ 1.0)

      See watch call parameters:

      recs_only: If set to `true`, an Update call containing behavior[play] should be sent on the initial video
      If `false` then the Watch call will also indicate the start of play of the initial video.

      Sample API Call:

      User BTORW starts second video on site VideoPublisher

      Call

      http://api.iris.tv/update?platform_id=343YOW&platform=VideoPublisher&access_token=996JVD321AZ&user_id=BTORW&client_token=99999&experience=53ebec0d321d0690858dw5r1&behavior[play]=1

      Response

      {
      "success": true,
      "behavior": {
      "play": 1
      },
      "experience": "53ebec0d321d0690858dw5r1"
      }

      Errors

      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 your Client Credentials

      Refer Here for documentation on OAuth

       

      Invalid Client Token

      Status Code: 401 Unauthorized
      IRIS.TV Response: “IRIS API: Check your authentication credentials”
      Problem: Client Token is Incorrect

       

      No Experience Included

      Status Code: 400 Bad Request
      IRIS.TV Response: "Message: invalid experience"
      Problem: Experience is missing from update call
      Solution: Double check the parameters being sent in on the update call. If still invalid, contact IRIS.TV support.

      Next Call

      The Next call requests continues an experience with a new set of recommendations based upon user interaction with the content. A next call should be made whenever the recommends need to be refreshed while maintaining the same experience value.

      Scenarios for a Next Call:
      1. User watches all assets in the initial Watch Call
      2. User responds with either a like or dislike that alters the recommendation calculation

       

      NOTE: When making a Next call after an Update call, make sure the Next call comes after receiving the IRIS API response from the Update call.

      platform_id: the reference ID from the publisher’s CMS
      platform: the name of the publisher
      number: the number of recommendations to be displayed in the response
      access_token: created via OAuth 2 standard
      user_id: ID associated to the individual user
      client_token: string of characters to authorize the client
      experience: Value that defines current stream of videos (generated on Watch call)

      Sample Workflow

      Client VideoPublisher requests a refresh in recommendations for user faf9183a

       

      Documentation for creating access tokens

      Call

      http://api.iris.tv/next?platform_id=46YDPA&platform=VideoPublisher&number=5&access_token=996JVD321AZ&user_id=faf9183a&client_token=99999&experience=53ebec0d321d0690858dw5r1

      Response

      jQuery191028397097534104254_1407970311998({
        'success': true,
        'next': [
          {
            'iris_id': '51084789cd5f272312231105',
            'platform': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_6.mp4',
            'platform_id': '908JOL',
            'title': 'The Grapefruit Theif',
            'release_date': '2012-10-22 12:30:58 UTC',
            'reviewed': '2013-02-05 23:02:24 UTC',
          },
          {
            'iris_id': '539a5ba7f09c3f00172310bb',
            'platform': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_7.mp4',
            'platform_id': '874KFR'',
            'title': 'The Bird Baron Trailer',
            'release_date': '2014-06-12 20:51:53 UTC'
          },
          {
            'iris_id': '53cdc6233459980016231012',
            'platform': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_8.mp4',
            'platform_id': '891RGB',
            'title': 'Orson Welles UK Teaser Trailer',
            'release_date': '2014-07-20 19:51:07 UTC'
          },
          {
            'iris_id': '51084760cd5f2723122310a1',
            'platform': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_9.mp4',
            'platform_id': '908MAR',
            'title': 'Early Morning Moon Clip',
            'release_date': '2012-11-30 05:48:51 UTC',
            'reviewed': '2013-09-06 22:35:10 UTC',
          },
          {
            'iris_id': '53814f1af1585f0032231014',
            'platform': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_10.mp4',
            'platform_id': '56YLI',
            'title': 'C Grodin International Trailer',
            'release_date': '2014-05-24 19:33:28 UTC'
          }
        ],
        'experience': '53ebec0d321d0690858dw5r1'
      })

      Video Parameters In Next Response:

      iris_id: IRIS.TV’s Reference ID for video
      platform: the name of the publisher
      content_URL: Link to video file on publisher’s CMS (only available if sent in during import process)
      platform_id: the Reference ID from the publisher’s CMS
      title: Title of video via publisher’s CMS
      release_date: Date when asset could be recommended
      reviewed: Date when asset was reviewed by IRIS.TV staff
      experience: Value that defines the current stream of videos.

      Errors

      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 your Client Credentials

      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.

       

      Playing Video Assets Sequentially

      The IRIS.TV API offers a lot of flexibility in how recommendations can be integrated into continuous streaming environments. This workflow will cover the API calls needed to handle an Adaptive Stream with no user interaction.

      Needed Calls:

      1. Watch Call

      http://api.iris.tv/watch?platform_id=241YOFG&platform=VideoPublisher&number=5&access_token=996JVD321AZ&user_id=BTORW&client_token=99999

      2. Update Call with "behavior" parameters "[next_auto]=1" "[video_complete]=1"

      http://api.iris.tv/update?platform_id=241YOFG&platform=VideoPublisher&access_token=996JVD321AZ&user_id=BTORW&client_token=99999&experience=53ebec0d321d0690858dw5r1&behavior[next_auto]=1&behavior[video_complete]=1

      3. Update Call with "behavior" parameter "[play]=1"

      http://api.iris.tv/update?platform_id=343YOW&platform=VideoPublisher&access_token=996JVD321AZ&user_id=BTORW&client_token=99999&experience=53ebec0d321d0690858dw5r1&behavior[play]=1

      4. Next Call

      http://api.iris.tv/next?platform_id=46YDPA&platform=VideoPublisher&number=5&access_token=996JVD321AZ&user_id=BTORW&client_token=99999&experience=53ebec0d321d0690858dw5r1

      Example

      Client seeking is serve recommendations to user BTORW. This stream has no user interaction from BTORW. Incandenza is requesting five assets, holding those in a playlist, and is requesting new assets once all four have been watched.

      Step 1: Create the Access Token

      Once the player has loaded, IRIS.TV recommends automatically creating the Access Token to decrease latency for the first Watch call. The Access Token will be created server-side and follows the OAuth 2 standard. Below is the Curl route for creating access tokens, but these can be created using a variety of languages. For detailed information on creating access token, please refer to OAuth Workflow.

      curl -i http://api.iris.tv/oauth/access_token \
        -F grant_type=none \
        -F client_id=0901c989d10  \
        -F client_secret=0980084019 \
        -F scope=iris_tv \

      Result:

       HTTP/1.1 100 Continue
        
      HTTP/1.1 200 OK
        
      {"access_token":"996JVD321AZ","scope":"iris_tv"}

      Step 2: Initiate the Experience

      BTORW has clicked the asset titled “Birdman International Teaser,” which has the platform_id “241YOFG.” Client VideoPublisher is requesting four recommendations.
      This call will be sent to the API:

      http://api.iris.tv/watch?platform_id=241YOG&platform=VideoPublisher&number=5&access_token=996JVD321AZ&user_id=BTORW&client_token=99999

      The response from IRIS.TV:

      jQuery191028397097534104254_1407970311998({
        'success': true,
        'next': [
          {
            'iris_id': '2140j908',
            'platform': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_0.mp4',
            'platform_id': '241YOG',
            'title': 'Birdman International Trailer',
            'release_date': '2014-08-01 18:34:33 UTC'
          },
          {
            'iris_id': '51084789cd5f272312231105',
            'platform': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_1.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': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_2.mp4',
            'platform_id': '780YOTSDB'',
            'title': 'Blue Heron Teaser Trailer',
            'release_date': '2014-06-12 20:51:53 UTC'
          },
          {
            'iris_id': '53cdc6233459980016231012',
            'platform': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_3.mp4',
            'platform_id': '9019YOPW',
            'title': 'Nelson Simcoe Clip',
            'release_date': '2014-07-20 19:51:07 UTC'
          },
          {
            'iris_id': '51084760cd5f2723122310a1',
            'platform': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_4.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': 'VideoPublisher',
            'content_url': 'http://www.credenza.com/asset_5.mp4',
            'platform_id': '46YDPA',
            'title': 'Paleo Diet International Trailer',
            'release_date': '2014-05-24 19:33:28 UTC'
          }
        ],
        'experience': '53ebec0d321d0690858dw5r1'
      })

      Incandenza will then hold this series of recommendations within a playlist. All future calls to IRIS.TV within this experience will also include the Experience value IRIS.TV sends in the response.

      Step 3: Send Video Complete Update for first asset

      BTORW has watched the first asset.
      Incandenza sends following call to IRIS.TV:

      http://api.iris.tv/update?platform_id=241YOFG&platform=VideoPublisher&access_token=996JVD321AZ&user_id=BTORW&client_token=99999&experience=53ebec0d321d0690858dw5r1&behavior[next_auto]=1&behavior[video_complete]=1&behavior[percentage_watched]=1

      Note: The addition of the experience value in the Update call

      Response from IRIS.TV API

      {
      "success": true,
      "behavior": {
      "next_auto": 1,
      video_complete: 1
      "percentage_watched": 1
      },
      "experience": "53ebec0d321d0690858dw5r1"
      }

      Step 4: Send Play Notification for Second Asset

      Once the second asset starts playing, Incandenza sends an Update call that informs IRIS.TV of a new asset.

      http://api.iris.tv/update?platform_id=343YOW&platform=VideoPublisher&access_token=996JVD321AZ&user_id=BTORW&client_token=99999&experience=53ebec0d321d0690858dw5r1&behavior[play]=1

      Response from IRIS.TV API

      {
      "success": true,
      "behavior": {
      "play": 1
      },
      "experience": "53ebec0d321d0690858dw5r1"
      }

      Continue the Update Workflow for the entire playlist. Once you reach the playlist, the recommendations will have to be refreshed.

       

      Refreshing Recommendations

      User BTORW has watched all videos from the Watch call.

      Step 1: Send Video Complete Update for last asset

      Send Update Call with parameters “behavior” parameters “behavior[next_auto]=1” “behavior[video_complete]=1” “behavior[percentage_watched]=1” to IRIS.TV:

      http://api.iris.tv/update?platform_id=46YDPA&platform=VideoPublisher&access_token=996JVD321AZ&user_id=BTORW&client_token=99999&experience=53ebec0d321d0690858dw5r1&behavior[next_auto]=

      Response from IRIS.TV

      {
      "success": true,
      "behavior": {
      "next_auto": 1,
      video_complete: 1
      "percentage_watched": 1
      },
      "experience": "53ebec0d321d0690858dw5r1"
      }

      Step 2: Send Next Call with ID from last asset

      NOTE: Make the Next call after receiving the IRIS API response from the Update call

      http://api.iris.tv/next?platform_id=46YDPA&platform=VideoPublisher&number=5&access_token=996JVD321AZ&user_id=BTORW&client_token=99999&experience=53ebec0d321d0690858dw5r1

      Response from IRIS.TV:

      jQuery191028397097534104254_1407970311998({
       'success': true,
       'next': [
       {
       'iris_id': '51084789cd5f272312231105',
       'platform': 'VideoPublisher',
       'content_url': 'http://www.credenza.com/asset_6.mp4',
       'platform_id': '908JOL',
       'title': 'The Grapefruit Theif',
       'release_date': '2012-10-22 12:30:58 UTC',
       'reviewed': '2013-02-05 23:02:24 UTC',
       },
       {
       'iris_id': '539a5ba7f09c3f00172310bb',
       'platform': 'VideoPublisher',
       'content_url': 'http://www.credenza.com/asset_7.mp4',
       'platform_id': '874KFR'',
       'title': 'The Bird Baron Trailer',
       'release_date': '2014-06-12 20:51:53 UTC'
       },
       {
       'iris_id': '53cdc6233459980016231012',
       'platform': 'VideoPublisher',
       'content_url': 'http://www.credenza.com/asset_8.mp4',
       'platform_id': '891RGB',
       'title': 'Orson Welles UK Teaser Trailer',
       'release_date': '2014-07-20 19:51:07 UTC'
       },
       {
       'iris_id': '51084760cd5f2723122310a1',
       'platform': 'VideoPublisher',
       'content_url': 'http://www.credenza.com/asset_9.mp4',
       'platform_id': '908MAR',
       'title': 'Early Morning Moon Clip',
       'release_date': '2012-11-30 05:48:51 UTC',
       'reviewed': '2013-09-06 22:35:10 UTC',
       },
       {
       'iris_id': '53814f1af1585f0032231014',
       'platform': 'VideoPublisher',
       'content_url': 'http://www.credenza.com/asset_10.mp4',
       'platform_id': '56YLI',
       'title': 'C Grodin International Trailer',
       'release_date': '2014-05-24 19:33:28 UTC'
       }
       ],
       'experience': '53ebec0d321d0690858dw5r1'
      })

      Step 3: Refresh playlist with new assets

       

      Step 4: Send Update Call for next video

      VideoPublisher sends update for play=1 update for the asset titled “The Grapefruit Theif” with platform_id “908JOL”

      Sample call:

      http://api.iris.tv/update?platform_id= 570ETA&platform=VideoPublisher&access_token=996JVD321AZ&user_id=BTORW&client_token=99999&experience=53ebec0d321d0690858dw5r1&behavior[play]=1

      Response from IRIS.TV API:

      {
      "success": true,
      "behavior": {
      "play": 1
      },
      "experience": "53ebec0d321d0690858dw5r1"
      }