clips > get

Tutorials, technical documents and downloads

API: Reference

Rev. Jan. 10, 2017

Description

Requesting Clip or Ad info

Required Credential Permission

GET [Signed + Unsigned Requests]

NOTE: Unsigned requests will only return data from active and approved Clips. Additionally, media and subtitle lists will not be included in the return.

Print

IMPORTANT!
When using signed requests it is responsibility of the Application:
1) Determine whether to display the Clip to the User or not (the API will return the Clip info regardless of being restrcited or not). The application must first check if the User has permission to access the Clip (by using the API call users > get_cvr ) and then decide what to do.
2) Check whether the Clip is active or not (the API will return the Clip regardless of its status). Possible status values are: 0 (inactive), 1 (active), 2 (pending moderation).
3) The URL of the media (video files) can contain the following prefixes [cfsig] and [xtok]
• If you find the [cfsig] prefix, then the URL requires CloudFront signature.
     To get the signed URL (at playback time) use the API call clips > get_aws_signed_url
• If you find the [xtok] prefix, then the URL requires External tokenization.
     To get the tokenized URL (at playback time) use the API call clips > get_xtokenized_url
4) If a Clip is on sale (restricted / the user is not authorized to access it and the "on_sale" field = 1) and the Clip has a "Trailer" file associated (with the media), then the application must allow the access to the Clip and playback the corresponding "Trailer" file.
5) Determine whether to offer the media file download option to the User by looking at the values of the fields: "downloadable_condition", "downloadable" and "downloadable_xfiles"
• downloadable_condition: The condition to offer the file download option
     0 = Always: Always check the "downloadable" setting (see below).
     1 = Depending on purchase: Check the "downloadable" setting only if the Clip is on sale and the User has permission to access it; otherwise, don't offer the download option.
• downloadable (depending on "downloadable_condition"): To offer download options for the User
     0 = No (don't offer the download option).
     1 = Yes, WebTV Files (allow the download of the files on the Clip media list).
     2 = Yes, WebTV Files + Other Files (like 1 but also include the files specified on the "downloadable_xfiles" field)
     3 = Yes, Other files only (only allow the download of the files specified on the "downloadable_xfiles" field)
• downloadable_xfiles: Links to other downloadable files.
Format: One URL per line. Each URL can be specified alone or with a label. Example:
     URL only: http://www.myserver.com/folder/myfile.mp4
     URL with label (label + 3 dashes + URL): Label---http://www.myserver.com/folder/myfile.mp4

Building the Request

Request URL and GET vars

GET vars specific to this request:

Var	Value	Description
go	clips	The API section
do	get	The API action
iq	*Clip ID*	The Clip or Ad ID

Resulting Request URL:
The resulting request URL would be similar to this (don't forget to append the required info: key, timestamp, salt and signature):
https://....../api.php?go=clips&do=get&iq={clip_id}&{required information}

POST vars

The following POST vars are optional

Var	Value	Description
generateEmbedCode	(int) *0\|1*	If 1, the corresponding Embed codes will be generated.
embedWidth	(int) *width*	Width for the embed code (in pixels)
embedHeight	(int) *height*	Height for the embed code (in pixels)
embedURLVars	(string) *"&var1=value1..."*	Video Player URL vars for the Embed code (check the possible URL vars here)

Response Examples

If the request was successful, you'll receive a response containing:
• data: The Clip info.
• media: The list of media files (videos) associated to the Clip.
• media_mbr: [WS.WebTV 1.9+] The Multi-Bitrate URLs associated with the Clip (Flash/F4M, HTML5/DASH).
• subtitles: The list of subtitles.
• interactivities: [WS.WebTV 1.9+] The list of Interactivities.
• channels: The list of Channels where the Clip is included.
• categories: The list of Categories associated with the Clip.
Example:

{
    "data": {
        "ad_is_channel_mid_roll": "0",
        "ad_is_channel_pre_roll": "0",
        "ad_is_clip_pre_roll": "0",
        "ad_link": "",
        "ad_policy": "0",
        "admin_template": "",
        "allow_comments": "1",
        "aspect": "1.78",
        "clicks": "0",
        "date": "1381911153",
        "date_formatted": "16\/10\/2013 10:12:33 AM",
        "date_lastmod": "1423210557",
        "date_lastmod_formatted": "06\/02\/2015 09:15:57 AM",
        "description": "<p>Clip description<\/p>",
        "description_seo": "Clip description",
        "dislikes": "1",
        "dislikes_formatted": "1",
        "downloadable": "0",
        "downloadable_condition": "0",
        "downloadable_xfiles": "",
        "duration": "8",
        "duration_formatted": "00:08",
        "id": "45",
        "id_imdb": "",
        "id_import": "",
        "id_user": "1",
        "img_icon": "http:\/\/......\/uploads\/images\/clip_45_1390047394_icon.jpg",
        "img_poster": "http:\/\/......\/uploads\/images\/clip_45_1390047394_poster.jpg",
        "img_social": "http:\/\/......\/uploads\/images\/clip_45_1390047394_social.jpg",
        "img_thumbnail": "http:\/\/......\/uploads\/images\/clip_45_1390047394_thumb.jpg",
        "interactivity_randomization": "0",
        "interactivity_spacing": "1",
        "interactivity_start_delay": "1",
        "interactivity_timing": "0",
        "is_3d": "0",
        "is_360": "0",
        "is_ad": "0",
        "is_featured": "1",
        "is_indexable": "1",
        "is_searchable": "1",
        "is_skippable": "1",
        "is_skippable_after": "0",
        "is_visitable": "1",
        "likes": "1",
        "likes_formatted": "1",
        "privacy": "0",
        "privacy_access_level": "99",
        "socialize": "1",
        "sprite_img": "http:\/\/......\/uploads\/images\/clip_45_1390926596_sprite.jpg",
        "sprite_vtt": "http:\/\/......\/uploads\/images\/clip_45_1390926596_sprite.vtt",
        "status": "1",
        "status_moderation": "1",
        "store_on_sale": "0",
        "store_play_trailer": "1",
        "tags": "tag1, tag2, tag3, tag4",
        "title": "This is a sample Clip",
        "title_url": "this-is-a-sample-clip",
        "type": "1",
        "type_name": "streamclip_vod",
        "url": "http:\/\/......\/index.php\/video\/45\/ws-webtv\/",
        "user_alias": "WebTV",
        "user_url": "http:\/\/......\/index.php\/portal\/user\/1\/webtv\/",
        "views": "346",
        "views_complete": "42",
        "views_complete_formatted": "42",
        "views_embed": "7",
        "views_embed_formatted": "7",
        "views_formatted": "346",
        "views_page": "206",
        "views_page_formatted": "206"
    },
    "media": {
        "0": {
            "id": "4843",
            "id_quality": "2",
            "vod_flash": "http:\/\/......\/uploads\/movies\/myvideo-hq.mp4",
            "vod_html5_h264": "http:\/\/......\/uploads\/movies\/myvideo-hq.mp4",
            "vod_html5_webm": "",
            "live_flash": "",
            "live_ios": "",
            "live_rtsp": "",
            "live_ms": "",
            "embed_flash": "",
            "embed_html5": "",
            "vod_flash_trailer": "",
            "vod_html5_h264_trailer": "",
            "vod_html5_webm_trailer": ""
        },
        "1": {
            "id": "4844",
            "id_quality": "3",
            "vod_flash": "http:\/\/......\/uploads\/movies\/myvideo-normal.mp4",
            "vod_html5_h264": "http:\/\/......\/uploads\/movies\/myvideo-normal.mp4",
            "vod_html5_webm": "",
            "live_flash": "",
            "live_ios": "",
            "live_rtsp": "",
            "live_ms": "",
            "embed_flash": "",
            "embed_html5": "",
            "vod_flash_trailer": "",
            "vod_html5_h264_trailer": "",
            "vod_html5_webm_trailer": ""
        },
        "2": {
            "id": "4845",
            "id_quality": "1",
            "vod_flash": "",
            "vod_html5_h264": "",
            "vod_html5_webm": "",
            "live_flash": "",
            "live_ios": "",
            "live_rtsp": "",
            "live_ms": "",
            "embed_flash": "",
            "embed_html5": "",
            "vod_flash_trailer": "http:\/\/......\/uploads\/movies\/myvideo-low.mp4",
            "vod_html5_h264_trailer": "http:\/\/......\/uploads\/movies\/myvideo-low.mp4",
            "vod_html5_webm_trailer": ""
        }
    },
    "media_mbr": {
        "flash": "http://../f4m_manifest.f4m",
        "html5": "http://../dash_manifest.mpd"
    },
    "subtitles": [],
    "interactivities": {
        "settings": {
            "timing": "absolute",
            "start_delay": -1,
            "spacing": -1,
            "randomize": -1
        },
        "list": [
            {
                "clicks": "18",
                "closable": "1",
                "content": "http://pubads.g.doubleclick.net/....&LR_SCHEMA=vast2",
                "contentType": "vast",
                "duration": -1,
                "end": "8",
                "height": "0",
                "id": "141",
                "link": "",
                "relative_position": -1,
                "start": "5",
                "views": "529",
                "width": "0"
            },
            {
                "clicks": "1",
                "closable": "0",
                "content": "Click for more info here!",
                "contentType": "text",
                "duration": -1,
                "end": "4",
                "height": "0",
                "id": "142",
                "link": "http://interactivity_link/",
                "relative_position": -1,
                "start": "1",
                "views": "381",
                "width": "0"
            }
        ]
    },
    "channels": [{
        "id": "1",
        "title": "Video Channel 1"
    }],
    "categories": [{
        "id": 7,
        "title": "Animation",
        "breadcrumb": [{
            "id": "1",
            "title": "Movies"
        }, {
            "id": 7,
            "title": "Animation"
        }]
    }]
}

If the request failed (for example, if the Credential does not have permission to GET), you'll receive a response like the following:

{
	"error"		 : "REQUEST_ERROR",
	"error_long" : "Permission error: GET"
}

Possible Error Messages
Besides the general errors, this request can return the following errors:

• REQUEST_ERROR | Invalid Clip ID:
Clip ID is not numeric or lower than 1.

• REQUEST_ERROR | Clip not found, inactive or restricted

PHP Example Code

Preparing GET and POST data.

// The GET vars
$GET_VARS = array( 
					"go"        => "clips",
					"do"        => "get",
					"iq"        => 45
					);

// The POST vars
$POST_VARS = array();

Generating the salt, timestamp, signature and sending the request
*** The following code block is common to all signed requests ***

// Collect the API Base URL and Credential info
$API_URL = "https://www.mywebtvdomain.tv/api.php";
$API_KEY_ID = "1b323a1cb879fd4e66530fbad07a32ee"; 
$API_SHARED_SECRET = "MWIzMjNhMWNiODc5ZmQ0ZTY2NTMwZmJhZDA3YTMyZWViOTQ3MDJiOGM2ZTU2NjE3"; // keep this safe!!!

// Generating salt and timestamp
$salt = md5(mt_rand());
$timestamp = time();
$signature = base64_encode(hash_hmac('sha256', $salt.$timestamp, $API_SHARED_SECRET, true));

// Generating the validation signature
// - Default method: using base64_encode(hash_hmac(...))
$signature = base64_encode(hash_hmac('sha256', $salt.$timestamp, $API_SHARED_SECRET, true)); // comment this line if using the next method
// - Simplified method - available since v60: using md5(). 
//   This method requires the variable $API_SIGNATURE_GENERATION_MODE = 1; in the config/Config.inc.php file.
// $signature = md5($salt."-".$timestamp."-".$API_SHARED_SECRET); // you must "uncomment" this line when using the simplified method

// Append the timestamp, salt, key and signature to the GET vars
$GET_VARS["timestamp"] = $timestamp; 	// UTC timestamp
$GET_VARS["salt"] = $salt;
$GET_VARS["key"] = $API_KEY_ID ;      // The API Key ID: This is public and is used by the API to identify the application;
$GET_VARS["signature"] = $signature;

// Create the request URL. Please note that if you do not use PHP buit in function 
// to create the HTTP query then don't forget to URL encode the values
$REQUEST_URL = $API_URL."?".http_build_query($GET_VARS); 
// The previous will build an URL like .../api.php?go=api_subject&do=api_action&etc...

// Create a new cURL resource and set the appropriate options
$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, $REQUEST_URL); 
curl_setopt($ch, CURLOPT_POST, true); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $POST_VARS);
// If your PHP host does not have a valid  SSL certificate, you will need to turn off SSL
// Certificate Verification. This is dangerous (!), and should only be done temporarily
// until a valid certificate has been installed
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); // Turns off verification of the SSL certificate.
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // Turns off verification of the SSL certificate.

// Sending the request to the API
$response = curl_exec($ch);

// Processing the response
if (!$response) { 
	echo 'API call failed'; 
} 
else
{
	print_r(json_decode($response,true)); 
}

clips > get | WS.WebTV API Reference | WebTV Solutions

Professional and affordable online video solutions

API: Introduction

API: Reference

API: Reference

clips > get

Description

Required Credential Permission

Building the Request

Request URL and GET vars

POST vars

Response Examples

PHP Example Code