API – Videos: Create, Check Status, Get Info, Update, Delete

by | Jan 26, 2015 | API

Create Video

To create a new video record, make a POST request to this URL:

https://api.field59.com/v2/video/create

Request

This request should contain a single parameter named “xml”. That parameter should contain an XML string with the information you want recorded into our system:

POST /v2/video/create HTTP/1.1
Content-Type: application/xml
Authorization: username:password
Host: api.field59.com
Expect: 100-continue
<?xml version="1.0" encoding="UTF-8"?>
<video>
     <title><![CDATA[API Video Test]]></title>
     <url><![CDATA[FULLY ENCODED URL TO LOCATION OF VIDEO ORIGINAL]]></url>
     <account><![CDATA[ACCOUNT]]></account>
     <image>
         <url><![CDATA[FULLY ENCODED URL TO LOCATION OF IMAGE FILE]]></url>
         <alt><![CDATA[text for alt tag on image (optional)]]></alt>
         <title><![CDATA[Title for image (optional)]]></title>
     </image>
     <tags>
        <tag><![CDATA[test]]></tag>
        <tag><![CDATA[test2]]></tag>
     </tags>
     <captions>
        <embedded>true</embedded>
        <sidecar_url><![CDATA[FULLY ENCODED URL TO LOCATION OF TIMED-TEXT SIDECAR FILE (TTML or SRT)]]></sidecar_url>
     </captions>
     <category><![CDATA[category]]></category>
     <summary><![CDATA[This is an api test video]]></summary>
     <description><![CDATA[This is an api test video]]></description>
     <schedule>
        <live_date><! [CDATA[2014-10-10 9:55pm]]></live_date>
        <dead_date><! [CDATA[2014-10-17 11:55pm]]></dead_date>
        <timezone>America/Chicago</timezone>
     </schedule>
     <delete_date><! [CDATA[2014-10-17 11:55pm]]></delete_date>
</video>

The minimum required items to successfully create a video are: title and url, but as much information that is available can be provided. Wrap all text in CDATA markup. All URLs should be URL-encoded. If a parameter is not available or in use, omit the node.

<account> The account the video will be associated with. ONLY valid if the API user is associated with multiple accounts.

<category> Field59 categories (automotive, business, culture, education, entertainment, games, health, information, lifestyle, news, politics, religion, shopping, sports, technology, travel, weather). Default is news.

<tag> Keywords for the video. Tags with spaces are not supported in the Field59 manager user interface. Please convert spaces in multiple-word keywords to hyphens prior to sending to Field59.

<embedded> Set to “true” or “1” if the video contains embedded captions.

<sidecar_url> URL of either a TTML/DFXP, SRT or VTT format of timed-text caption files.

<summary> Summary for the video.

<description> Longer description for the video.

<live_date> Date and time for the video to go live.
Valid values: any valid PHP date format; see http://www.php.net/manual/en/datetime.formats.date.php
         Example: 2013-10-17 10pm

<dead_date> Date and time for the video to expire.
Valid values: see live parameter
Default: none

<delete_date> Date and time for the video to be marked as deleted.
Valid values: see live parameter
Default: none

<timezone> The timezone of the live_date and dead_date parameters.
Valid values: one of http://www,php.net/manual/en/timezones.php
Default: UTC
Example: America/Chicago

Response
If the video has been successfully registered, the server will respond with a 200 OK response, and an XML response with a video node containing the key of the newly created video and links to available actions that can be followed by your application to perform subsequent actions.

HTTP/1.1 200 OK
<?xml version="1.0"?>
<createresponse>
      <video>
            <key><![CDATA[FILE KEY]]></key>
      </video>
      <actions>
            <postUpdatedVideoInfo>https://api.field59.com/v2/video/[FILE KEY]</postUpdatedVideoInfo>
            <deleteVideo>https://api.field59.com/v2/video/[FILE KEY]</deleteVideo>
            <getVideoInfo>https://api.field59.com/v2/video/[FILE KEY]</getVideoDetails>
            <getVideoStatus>https://api.field59.com/v2/video/status/[FILE KEY]</getVideoStatus>
      </actions>
</createresponse>

Code Example

In PHP, use curl to make the request.

<?php
try{
      $xml = '<?xml version="1.0" encoding="UTF-8"?>
             <video>
             <title><![CDATA[Video Title]]></title>
             <url><![CDATA['. urlencode('VIDEO URL').']]></url>
             </video>';
     $url = 'https://api.field59.com/v2/video/create';
     $ch = curl_init($url);
     curl_setopt($ch, CURLOPT_POST, 1);
     curl_setopt($ch, CURLOPT_POSTFIELDS, "xml=" . $xml);
     curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
     curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
     $content = curl_exec($ch);
     $response = curl_getinfo($ch);
     print_r($content);
     print_r($response);
     curl_close($ch);
} catch (Exception $e) {
     var_dump($e);
}

Sending files

As long as the location of your video files is public and valid, you may use any location to send assets using the Field59 API. This includes FTP servers, Amazon S3, Dropbox, Google Drive, etc. For example:

Assets to be stored on FTP are:

  • Video File
  • Thumbnail Image (optional)
  • Closed Caption Sidecar File (optional)

The FTP server you use must be publicly available for the API to fetch its contents. Please use a folder structure that makes sense to you and your development team that follows a consistent naming convention.

Please allow for all assets to be fully uploaded to the server before beginning the Field59 API calls. (Best practice: run a command to confirm the files are in their intended location and the proper file types set for each.)

Please allow the files to be stored for a period of time (5-10 minutes) as to let the API run re-tries in the case of failed attempts. (Best practice: run a cron script every 24 hours to delete old files.)

Check Video Status

To check the availability/status of any video in the system, make a GET request from the following url:

https://api.field59.com/v2/video/status/[FILE KEY]

Request

GET /v2/video/status/[FILE KEY] HTTP/1.1
Content-Type: application/xml
Authorization: username:password
Host: api.field59.com
Expect: 100-continue

Note: A completely formatted url is part of the response to a video create request, so if you will need to make follow up status calls, you can simply parse the response to the create command and then store the url from the “actions” node in the response.

Response

HTTP/1.1 200 OK
<?xml version="1.0"?>
<video>
<key><![CDATA[FILE KEY]]></key>
 <status><![CDATA[ new | queued | processing | ready | error ]]></status>
</video>
<actions>
<getVideoDetails>https://api.field59.com/v2/video/[FILE KEY]</getVideoDetails>
<getVideoStatus>https://api.field59.com/v2/video/status/[FILE KEY]</getVideoStatus>
</actions>

Get Video Info

To get information about a video in the system, make a GET request from the following url:

https://api.field59.com/v2/video/[FILE KEY]

Request

GET /v2/video/[FILE KEY][?timezone] HTTP/1.1
Content-Type: application/xml
Authorization: username:password
Host: api.field59.com
Expect: 100-continue

timezone: the timezone used to convert timestamps in results.
Valid values: one of http://www.php.net/manual/en/timezones.php
Default: UTC
Example: America/Chicago

Response

<?xml version="1.0"?>
        <video>
            <timeZone><![CDATA[America/Chicago]]></timeZone>
            <key><![CDATA[FILE KEY]]></key>
            <package_type><![CDATA[field59_v4]]></package_type>
            <title><![CDATA[conv]]></title>
            <status><![CDATA[ready]]></status>
            <source_url><![CDATA[VIDEO URL]]></source_url>
            <account><![CDATA[ACCOUNT]]></account>
            <category><![CDATA[category]]></category>
            <summary><![CDATA[summary]]></summary>            
            <description><![CDATA[description]]></description>
            <create_date><![CDATA[2013-10-08 17:16:29]]></create_date>
            <last_update><![CDATA[2013-10-08 17:19:10]]></last_update>
            <delete_date><! [CDATA[2014-10-17 11:55pm]]></delete_date>
            <deleted><![CDATA[]]></deleted>
            <captions>
                <embedded><![CDATA[1]]></embedded>
                <sidecarUrl><![CDATA[CAPTION FILE URL]]></sidecarUrl>
            </captions>
            <thumbnail_image>
                <key><![CDATA[FILE KEY]]></key>
                <title><![CDATA[Title]]></title>
                <url><![CDATA[FULL-SIZE IMAGE URL]]></url>
                <urlSmall><![CDATA[SMALL IMAGE URL]]></urlSmall>
                <urlMediaum><![CDATA[MEDIUM IMAGE URL]]></urlMedium>
                <alt></alt>
            </thumbnail_image>
            <tags>
            <tag><![CDATA[api]]></tag>
                  <tag><![CDATA[test]]></tag>
            </tags>
            <transcodes>
                <format>
                    <id><![CDATA[ID]]></id>
                    <format><![CDATA[fl9]]></format>
                    <title><![CDATA[Title]]></title>
                    <url><![CDATA[TRANSCODE URL]]></url>
                    <duration><![CDATA[17.74]]></duration>
                </format>
            </transcodes>
       </video>

Code Example

In PHP using curl to make the request:

<?php
try{
      $url = 'https://api.field59.com/v2/video/[FILE KEY]?timezone=America/Chicago';
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      curl_setopt($ch, CURLOPT_USERPWD, 'usernamehere:passwordhere');
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      $content = curl_exec($ch);
      com.dotmarketing.util.ServletResponseCharacterEncoding@164ca8bf = curl_getinfo($ch);
      print_r($content);
      print_r(com.dotmarketing.util.ServletResponseCharacterEncoding@164ca8bf);
} catch (Exception $e) {
    var_dump($e);
}

Update Video

To update an existing video record, you will need to make a POST request to this URL:

https://api.field59.com/v2/video/[FILE KEY]

Request

This request is otherwise identical to the Create Video request. It should contain a single parameter named “xml”. That parameter should contain an XML string with the information you want recorded into our system. Wrap all text in CDATA markup. All URLs should be URL-encoded. If a parameter is not available or in use, omit the node.

Delete Video

To delete a video record, make a DELETE request to this URL:

https://api.field59.com/v2/video/[FILE KEY]

Request

DELETE /v2/video/[FILE KEY] HTTP/1.1
Content-Type: application/xml
Authorization: username:password
Host: api.field59.com
Expect: 100-continue

Code Example

In PHP using curl to make the request:

<?php
try{
      $url = 'https://api.field59.com/v2/video/[FILE KEY]';
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      curl_setopt($ch, CURLOPT_USERPWD, 'usernamehere:passwordhere');
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
      $content = curl_exec($ch);
      com.dotmarketing.util.ServletResponseCharacterEncoding@164ca8bf = curl_getinfo($ch);
      print_r($content);
      print_r(com.dotmarketing.util.ServletResponseCharacterEncoding@164ca8bf);
} catch (Exception $e) {
    var_dump($e);
}
Share This