Articles

Print

API Video

Written by Chris Williams. Posted in API Documentation

The Video secton of the API is the most commonly used and thus the more complex element of the API, providing features to view, add, edit and remove videos from the 247 Platform.

 

Verbs

  • Get - Information on a video
  • Put - Create new video
  • Update - Updates details for a video
  • Authenticate - Create authentication for a user to watch a secured video
  • Status - Returns the current video status. 
  • IsPublishing - Returns a list of the stream(s) required for the live streaming of the video, and their current publishing status.
  • Delete - Remove the files for a video
  • UploadFormParams - Get the parameters needed to host your own upload form to S3
  • ListVideosByCategory - Get a list of videos for a specified category.
  • ListViewers - Get a list of users with geo locations who are watching a particular steam.
  • RemoveAuth - Disconnect a user from watch a stream.

 

Get

Returns the information on a video on the 247 Platform

Request

URL:

  • http://console.247platform.com/api/video/get/[video id]?sessionId=[Session ID]&userId=[Client Id]

Params: none.

Response

{
   "response":{
      "video":{
         "videoId":"12345",
         "title":"My Live Video",
         "categoryId":"230",
         "published":"1",
         "thumbnailKey":"https:\/\/s3-eu-west-1.amazonaws.com\/247platform-test\/247platform-images\/42\/12345\/custom-908.png",
         "live":{
            "formatId":"7",
            "enabled":true,
            "videoFormatSettings":{
               "videoFormatId":"7",
               "enabled":"1",
               "streamName":"2c-61e-live",
               "requiresAuth":"1"
            },
            "primaryStreamingDetails":{
               "protocol":"rtmp",
               "portNumber":"1935",
               "publicDNS":"46.137.7.26",
               "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com",
               "application":"origin",
               "stream":"2c-61e-live"
            },
            "backupStreamingDetails":{
               "protocol":"rtmp",
               "portNumber":"1935",
               "publicDNS":"46.137.7.26",
               "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com",
               "application":"origin",
               "stream":"2c-61e-live"
            },
            "publishString":{
               "protocol":"rtmp",
               "portNumber":"1935",
               "publicDNS":"46.137.7.26",
               "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com",
               "application":"origin",
               "stream":"2c-61e-live"
            }
         },
         "vod":{
            "formatId":"9",
            "enabled":true,
            "settings":{
               "protocol":"rtmp",
               "portNumber":"1935",
               "publicDNS":"46.137.7.26",
               "publicStreamingDNS":"ec2-46-137-7-26.eu-west-1.compute.amazonaws.com",
               "application":"vods3",
               "stream":"2c-61e-vod"
            }
         },
         "download":{
            "formatId":"8",
            "enabled":false
         }
      },
      "code":"200",
      "isOk":true
   },
   "code":"200"
}

Errors

  • ResourceNotFound (code 404), We are unable to locate the Video ID you requested
  • AuthenticationRequired (code 400), Authentication is required but not provided. 

 

 

Put

Create a new video on the 247 Platform.

Request

 URL:

  • http://console.247platform.com/api/video/put/?sessionId=[Session ID]&userId=[Client Id]&categoryId=[Category Id]&published=[1 or 0]

Params:

  • `videoTitle` (required), String, Title you wish to change the video to
  • `categoryId` (required), Integer, Category Id you wish to change this Video to
  • `published` (required), Integer, 1 for published, 0 for not.

 

Response

{
   "response":{
      "videoId":1705,
      "data":{
         "title":"My New Video",
         "categoryId":"270",
         "published":1,
         "ownerId":42
      },
      "clientId":42,
      "log":{
         "formats":{
            "live":"7",
            "vod":"9",
            "download":"8"
         },
         "uniqueIdentifer":"2c-78a",
         "streamNames":{
            "live":"2c-78a-live",
            "vod":"2c-78a-vod"
         }
      },
      "code":"200",
      "message":"Video has been added.",
      "isOk":true
   },
   "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.

 

Update

Updates the title, category and publish status of a video

Request

URL:

  • http://console.247platform.com/api/video/update/[Video Id]/?video=[JSON Object]&sesionId=[Session ID]&userId=[Client ID]

Params:

  • Video Id (Required), Int, ID of the video you wish to update
  • `video` (Required), String, The JSON reporesentation of the details you wish to update for the video, e.g.:
    {
       "title":"My New Title",
       "categoryId":4,
       "published":0
    }

Response

{
   "response":{
      "code":"200",
      "message":"Video Updated.",
      "isOk":true
   },
   "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.

Authenticate

Creates an authentication record for a users' IP against a video stream, providing them the ability to watch the video.  

Request

URL:

  • http://console.247platform.com/api/video/authenticate/?ip=[Viewer IP]&streamName=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]

Params: 

  • `ip` (Required), String, The IP address of the viewer

  • `streamName` (required), String, The stream name of the video you're authenticating the user to watch.

Response

{
   "response":{
      "clientIp":"192.168.100.1",
      "streamName":"aa-b1234-live",
      "authHash":"34ce63220112342cdb63204298788f323",
      "code":"200",
      "isOk":true
   }
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.

 

 

Status 

Returns the status of the video, so that it can be used to check the video's status before embedding the player, and handle errors in your own fashion.

Request

URL:

  • http://console.247platform.com/api/video/status/?streamName=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]

Params:

  • `streamName` (Required), String. the stream name of the video you wish the status of.
  • `ip` (optional), String, The viewers IP address, required if you wish to include a Geoblocking check against the user in the response. 

Response

{
   "response":{
      "video":{
         "live":true,
         "original":"2c-61e-live",
         "uniqueIdentifer":"2c-61e",
         "simpleName":"2c-61e-live"
      },
      "errors":[

      ],
      "code":"200",
      "isOk":true
   },
   "code":"200"
}

Possible Responses

The `errors` array can contain a number of possible keys and descriptions:

  • COM_PLATFORM247_EMBED_ERROR_NOTEXIST : The video doesn't exist
  • COM_PLATFORM247_EMBED_ERROR_VIDEONOTPUBLISHED - The video hasn't been published.
  • COM_PLATFORM247_EMBED_ERROR_CATEGORYNOTPUBLISHED - The category (or one of the parent categories) of this video hasn't been published.
  • COM_PLATFORM247_EMBED_ERROR_VIDEONOTENABLED - The requested format hasn't been abled for this video. 
  • COM_PLATFORM247_EMBED_ERROR_GEOBLOCKED - The video has been geoblocked for the given IP address

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.

 

 

Delete

Deletes any physical objects for a video such as recordings and thumbnails, does not  remove the video from the 247 Platform to ensure you continue to have access to log information. 

Request

URL

  • http://console.247platform.com/ap/video/delete/[Video Id]/?deleteThumbs=[deleteThumbs]

 Params

  • Video Id (Required), Integer, The Video ID that you're trying to delete
  • `deleteThumbs`, Integer, 1 or 0, if you wish to delete an thumbnail images also. 

Response

{
   "response":{
      "code":"200",
      "message":"VOD has been deleted.",
      "isOk":true
   },
   "code":"200"
}

Errors

 

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.

 

 

isPublishing

Returns the connection status of the streams required to publish the live stream.  For videos using more than one bitrate, it will return each individual required stream with it's own publishing status.

Request

URL:

  • http://console.247platform.com/api/video/ispublishing/?streamname=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]

Params

  • `streamName` (reqired) String - Stream name to verify

Response

{
   "response":{
      "isPublishing":{
         "isPublishing":{
            "1":{
               "name":"platform-example-270p-500",
               "publishing":1,
               "streamName":"2c-61e-live-1"
            },
            "2":{
               "name":"platform-example-360-1000",
               "publishing":1,
               "streamName":"2c-61e-live-2"
            },
            "3":{
               "name":"platform-example-360-1500",
               "publishing":0,
               "streamName":"2c-61e-live-3"
            },
            "4":{
               "name":"platform-example-540-2500",
               "publishing":0,
               "streamName":"2c-61e-live-4"
            },
            "5":{
               "name":"platform-example-576-3500",
               "publishing":0,
               "streamName":"2c-61e-live-5"
            }
         },
         "publishingOk":0
      },
      "timeoutSeconds":60,
      "code":"200",
      "isOk":true
   },
   "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.

 

 

UploadFormParams

Returns parameters required to host your own upload form for transferring files to an Amazon S3 Folder so that they can be transcoded through the 247 Platform.

Request

URL:

  • http://console.247platform.com/api/video/uploadformparams/?sessionId=[Session ID]&userId=[Client ID]

Response

{
   "response":{
      "policy":"eyJleHBpcmF0aW9uIjogIjIwMTMtMDYtMjBUMDk6MTE6MTlaIiwiY29uZGl0aW9ucyI",

      "signature":"KtzHA6RoypairnKrOsiY8UVadRFbsrM=",
      "AWSAccessKeyId":"dKtzsHA6eRoywpainqKrOieY8UVdRFbrM",
      "s3BucketName":"247platform-test",
      "key":"users\/635\/uploads\/${filename}",
      "scriptUrl":"http:\/\/247platform-test.s3.amazonaws.com\/"
      "code":"200",
      "isOk":true
   },
   "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.


Usage

Once you have the parameters above you can host your own upload form, we use the jQuery plugin 'uploadify' to implement our upload form. An example of an implementation with uploadify: http://www.flynsarmy.com/2011/03/upload-to-amazon-s3-with-uploadify/

Using the parameters in the example response above you would fill in the gaps as so:

<script type="text/javascript">
$(document).ready(function() {
    $("#file_upload").uploadify({
     'uploader' : '<?= WEBROOT ?>files/uploadify/uploadify.swf',
     'buttonText' : 'Browse',
     'cancelImg' : '<?= WEBROOT ?>files/uploadify/cancel.png',
     'script' : '<?=$this->apiResponse->scriptUrl ?>',
     'scriptAccess' : 'always',
     'method' : 'post',
     'scriptData' : {
     "AWSAccessKeyId" : "<?=$this->apiResponse->AWSAccessKeyId ?>",
     "acl" : "authenticated-read",
     "policy" : "<?=$this->apiResponse->policy ?>",
     "signature" : "<?=$this->apiResponse->signature ?>",
     "success_action_status" : "201",
     "key" : "<?=$this->apiResponse->key ?>",
     "fileext" : "",
     "Filename" : ""
},
  'fileExt' : '*.*',
  'fileDataName' : 'file',
  'simUploadLimit': 2,
  'multi' : true,
  'auto' : true,
  'onError' : function(errorObj, q, f, err) { console.log(err); },
  'onComplete' : function(event, ID, file, response, data) { console.log(file); }
  });
});
 </script> 

 

 

ListVideosByCategory

List your videos for a specified optional list of categoryids

Request

 URL:

  • http://console.247platform.com/api/video/listvideosbycategory/?sessionId=[Session ID]&userId=[Client Id]&categoryIds=[Category Ids]

Params:

  • `categoryIds` (optional), String, List of categories to pull videos for, format required is 1-2-3-4 (each category separated by a dash) if no category is specified we return all your videos

Response

 
[
  {
    "videoId":"9",
    "title":"test",
    "categoryId":"98",
    "published":"-2",
    "formats":[
      {
        "title":"Live Flash",
        "videoFormatId":"7",
        "isLive":"1",
        "isVod":"0",
        "isDownload":"0",
        "published":"1"
      }
    ]
  },
  {
    "videoId":"10",
    "title":"test",
    "categoryId":"98",
    "published":"1",
    "formats":[
      {
        "title":"VOD Flash",
        "videoFormatId":"9",
        "isLive":"0",
        "isVod":"1",
        "isDownload":"0",
        "published":"1"
      }
    ]
  },
  {
    "videoId":"11",
    "title":"vide 2",
    "categoryId":"98",
    "published":"1",
    "formats":[
      {
        "title":"Live Flash",
        "videoFormatId":"7",
        "isLive":"1",
        "isVod":"0",
        "isDownload":"0",
        "published":"1"
      },
      {
        "title":"VOD Flash",
        "videoFormatId":"9",
        "isLive":"0",
        "isVod":"1",
        "isDownload":"0",
        "published":"1"
      }
    ]
  }
]
 

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.

 

 

 

ListViewers (not yet available on the API)

Returns a list of users who are viewing a particular stream in the last 10 minutes.

Request

URL:

  • http://console.247platform.com/api/video/listviewers/?streamName=[Stream Name]&sessionId=[Session ID]&userId=[Client ID]

Params

  • `streamName` (reqired) String - Stream name to verify

Response

{
   "response":{
      "viewers":{

            {
               "ipaddress":"78.129.148.101",
               "country_name":"United Kingdom",
               "city_name":"London"
            },
            {
               "ipaddress":"94.197.127.197",
               "country_name":"United Kingdom",
               "city_name":"London"
            },
      },
      "code":"200",
      "isOk":true
   },
   "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.

 

 

RemoveAuth (not yet available on the API)

Disconnect a user from viewing a stream.

Request

URL:

  • http://console.247platform.com/api/video/removeauth/?streamName=[Stream Name]&ipAddress[IP Address]&sessionId=[Session ID]&userId=[Client ID]

Params

  • `streamName` (required) String - Stream name to verify
  • `ipAddress` (required) String - IP to disconnect

Response

{
   "response":{
      "code":"200",
      "isOk":true
   },
   "code":"200"
}

Errors

  • AuthenticationRequired (code 400), Authentication is required but not provided.
  • ResourceNotFound (code 404), One or more of the required params where not passed.
  • InternalError (code 500) The stream was not found or the user was found to not be watching the stream anymore