Introduction

The Viddler API exposes key features to clients that would like to build custom solutions using Viddler’s multimedia platform. In order to use Viddler’s API you must have a Viddler account that has API access enabled, and an active API key. If you do not have API access and would like to upgrade your account, please contact our sales department either via email: solutions@viddler.com or via phone at 1-888-444-1119.

Responsible Use Guidelines

We ask that you keep in mind the following to allow for the best API experience for all of our users:

Limit requests to no more than one per second, and only one request at a time

Cache response results for as long as possible when circumstances allow for it.

Protect user credentials by storing them no longer than necessary or at all.

Do not expose your API Key or user credentials when using our API with JavaScript.

Report issues through our Support Helpdesk, included with all accounts.

While the system is quite scalable, We may need to disable an API key due to abnormally high usage with that key. We will make an effort to contact you before this happens.

API Endpoint

HTTP: http://api.viddler.com/api/v2/{methodname.format}

HTTPS: https://api.viddler.com/api/v2/{methodname.format}

For example, to call viddler.api.getInfo using a PHP response format and using HTTPS: https://api.viddler.com/api/v2/viddler.api.getInfo.php

(In general, methods with “get” in their name involve GET requests, and methods with “set”, “remove”, or “upload” are POST/Multipart POST.)

Methods

Naming Convention

Viddler’s API uses the format of [scope].[group].[action]

Scope – method scope – this will always be “viddler” for public methods

Group – what this method affects – “users”,”videos”,”groups”, etc.

Action – what this method will perform – “register”,”getDetails”,”getByUser”, etc.

Common Parameters

api_key – Required – Each method must be authorized by your API Key. This is required by all methods, and will not be included in the documentation for each individual method.

sessionid - Recommended – In order to fully manipulate videos that belong to you (or get full details on those videos, accounts, etc) You will need to pass along a sessionid obtained from viddler.users.auth

video_id – This is the video’s ID – this can be found easily in the Video’s URL on Viddler.com (viddler.com/v/{video_id}) This can also referred to interchangeably as a “token”

Special Characters

When passing along special characters for parameters (usually as a part of a password) you should take care to urlencode the characters before sending them to the Viddler API.

Some methods include a paginated list of items. These methods use a unified response format in order to return list metadata in addition of pure list items. All paginated lists results will have a very similar, if not identical, schema. The list of results is listed in a nested array with a “tag” appropriate for its method. Sort tags are available for methods that allow for sorting.

“per_page” and Obtaining The Total Number of Pages

Most methods that return lists include per_page and page parameters. The maximum allowed value for the per_page parameter is 100.

While there is no upper limit for the page value, you can use the following information to obtain the total/maximum for a particular response:

total_count / per_page Round the result up to the nearest number. In PHP, for example, you can use the ceil() method.

Data Types

date, datetime – UNIX timestamp (number of seconds elapsed since 1 Jan 1970 UTC). For dates, time part will be ignored. Dates passed as method parameters are in YYYY-MM-DD format.

Booleans – responses will use only 0 (false) or 1 (true). Requests may contain 0/1, true/false, t/f, or yes/no. Any other value will be considered as “false.”

Floating-point numbers – will be scaled to the second decimal value (Ex: 42.187 will become 42.19)

Null values – The Viddler API will not return “null” values. Instead, they will be represented as an empty string.

Authentication

When using the Viddler API, your API key is not the only method of authorizing what you are able to do. As the API was built with the ability to manipulate data from multiple accounts, we also utilize a session ID, which can be obtained using the viddler.users.auth method. The session ID ties an API method to your account, enabling read/write of private information (your account data, information on private videos, etc.)

Platform API EULA

BY OBTAINING AN API PRODUCT KEY FROM VIDDLER, YOU AGREE TO BE BOUND BY AND BECOME A PARTY TO THIS AGREEMENT. IF YOU DO NOT AGREE TO ALL OF THE TERMS OF THIS AGREEMENT, YOU MAY NOT OBTAIN AN API KEY AND VIDDLER DOES NOT GRANT YOU A LICENSE TO USE THE APIs.

Viddler reserves the right to update and change, from time to time, the terms of this Agreement by posting the amended terms on the Developers Site. Except as stated below, all amended terms shall be effective thirty (30) days after they are initially posted on the Developers Site. Use of the API after the date on which such changes become effective shall constitute your acceptance of such changes.

GRANT OF API LICENSE – Subject to your (“Licensee’s”) full compliance with all of the terms and conditions of this API Agreement (“Agreement”), Viddler, Inc. (“Viddler”) grants Licensee a non-exclusive, revocable, non-sublicensable, non-transferable license to download and use the Viddler application program interface and other materials provided by Viddler (collectively, “APIs”) to develop, reproduce and distribute non-commercial applications that interoperate with Viddler.com or any other web property owned by Viddler. Licensee may not install or use the APIs for any other purpose, including without limit any commercial purpose, without Viddler’s prior written consent and execution of a Partner License Agreement. Requests for API keys intended for commercial use are reviewed by staff and a Partner License Agreement can be executed for commercial use.

Licensee shall not use the APIs in connection with or to promote any products, services, or materials that constitute, promote or are used primarily for the purpose of dealing in: spyware, adware, or other malicious programs or code, counterfeit goods, items subject to U.S. embargo, unsolicited mass distribution of email (“spam”), multi-level marketing proposals, hate materials, hacking/ surveillance /interception/ descrambling equipment, libelous, defamatory, obscene, pornographic, abusive or otherwise offensive content, prostitution, body parts and bodily fluids, stolen products and items used for theft, fireworks, explosives, and hazardous materials, government IDs, police items, gambling, professional services regulated by state licensing regimes, non-transferable items such as airline tickets or event tickets, weapons and accessories.
.In the event Viddler establishes API call volume limitations and Licensee exceeds such limitations, Viddler may discontinue Licensee’s use of the API and/or charge Licensee at the then-current rates for all API calls that exceed the limitations.

PROPRIETARY RIGHTS – As between Viddler and Licensee, the APIs and all intellectual property rights in and to the APIs are and shall at all times remain the sole and exclusive property of Viddler and are protected by applicable intellectual property laws and treaties.

OTHER RESTRICTIONS – Except as expressly and unambiguously authorized under this Agreement, Licensee may not (i) copy, rent, lease, sell, transfer, assign, sublicense, disassemble, reverse engineer or decompile (except to the limited extent expressly authorized by applicable statutory law), modify or alter any part of the APIs, or (ii) otherwise use the APIs on behalf of any third party. This Agreement does not include any right for Licensee to use any trademark, service mark, trade name or any other mark of Viddler or any other party or licensor. No rights or licenses are granted except as expressly and unambiguously set forth herein. If Licensee violates any of the foregoing restrictions, Viddler shall own all right, title and interest relating to any and all inventions, works of authorship, designs, know-how, ideas and information made or conceived or reduced to practice, in while or in part, using the APIs. Licensee hereby agrees to make all assignments necessary to accomplish the foregoing ownership.

WARRANTY DISCLAIMER – The APIs are provided “as is” without warranty of any kind. except to the extent required by applicable law, Viddler and its vendors each disclaim all warranties, whether express, implied or statutory, regarding the APIs, including without limitation any and all implied warranties of merchantability, accuracy, results of use, reliability, fitness for a particular purpose, title, interference with quiet enjoyment, and non-infringement of third-party rights. further, Viddler disclaims any warranty that licensee’s use of the apis will be uninterrupted or error free.

SUPPORT AND UPGRADES – This Agreement does not entitle Licensee to any support for the APIs, unless Licensee makes separate arrangements with Viddler as part of a Partner License Agreement and pays all fees associated with such support. Any such support provided by Viddler shall be subject to the terms of this Agreement.

LIABILITY LIMITATION – Regardless of whether any remedy set forth herein fails of its essential purpose or otherwise, and except for bodily injury, in no event will Viddler or its vendors, be liable to licensee or to any third party under any tort, contract, negligence, strict liability or other legal or equitable theory for any lost profits, lost or corrupted data, computer failure or malfunction, interruption of business, or other special, indirect, incidental or consequential damages of any kind arising out of the use or inability to use the apis, even if Viddler has been advised of the possibility of such loss or damages and whether or not such loss or damages are foreseeable. any claim arising out of or relating to this agreement must be brought within one (1) year after the occurrence of the event giving rise to such claim. in addition, Viddler disclaims all liability of any kind of Viddler’s vendors.

INDEMNITY – Licensee agrees that Viddler shall have no liability whatsoever for any use Licensee makes of the APIs. Licensee shall indemnify and hold harmless Viddler from any and all claims, damages, liabilities, costs and fees (including reasonable attorneys’ fees) arising from Licensee’s use of the APIs.

TERM AND TERMINATION – This Agreement shall continue until terminated as set forth in this Section. Either party may terminate this Agreement at any time, for any reason, or for no reason including, but not limited to, if Licensee violates any provision of this Agreement. Any termination of this Agreement shall also terminate the license granted hereunder. Upon termination of this Agreement for any reason, Licensee shall destroy and remove from all computers, hard drives, networks, and other storage media all copies of the APIs, and shall so certify to Viddler that such actions have occurred. Viddler shall have the right to inspect and audit Licensee’s facilities to confirm the foregoing. Sections 6 through 11 and all accrued rights to payment shall survive termination of this Agreement.

MODIFICATION. – Viddler reserves the right to update and change, from time to time, the terms of this Agreement by posting the amended terms on the Developers Site. Except as stated herein, all amended terms shall be effective thirty (30) days after they are initially posted on the Developers Site. IF ANY MODIFICATION IS UNACCEPTABLE TO YOU, YOUR ONLY RECOURSE IS TO TERMINATE THIS AGREEMENT BY SENDING A TERMINATION NOTICE TO NETSUPPORT(at)VIDDLER(dot)COM BEFORE THE EFFECTIVE DATE OF THE AMENDMENT(S). THE AMENDMENT. TERMINATION NOTICE WILL BE EFFECTIVE ON THE DATE IT IS RECEIVED BY VIDDLER. THE MOST CURRENT VERSION OF THE AGREEMENT WILL BE AVAILABLE ON THE DEVELOPERS SITE AND WILL SUPERCEDE ALL PREVIOUS VERSIONS OF THE AGREEMENT. USE OF THE API AFTER THE DATE ON WHICH SUCH CHANGES BECOME EFFECTIVE SHALL CONSTITUTE YOUR ACCEPTANCE OF SUCH CHANGES.

EXPORT CONTROLS – Licensee shall comply with all export laws and restrictions and regulations of the Department of Commerce, the United States Department of Treasury Office of Foreign Assets Control (“OFAC”), or other United States or foreign agency or authority, and Licensee shall not export, or allow the export or re-export of the APIs in violation of any such restrictions, laws or regulations. By downloading or using the APIs, Licensee agrees to the foregoing and represents and warrants that Licensee is not located in, under the control of, or a national or resident of any restricted country.

MISCELLANEOUS – This Agreement constitutes the entire agreement between Licensee and Viddler pertaining to the subject matter hereof, and supersedes any and all written or oral agreements with respect to such subject matter. This Agreement, and any disputes arising from or relating to the interpretation thereof, shall be governed by and construed under Pennsylvania law as such law applies to agreements between Pennsylvania residents entered into and to be performed within Pennsylvania by two residents thereof and without reference to its conflict of laws principles or the United Nations Conventions for the International Sale of Goods. Except to the extent otherwise determined by Viddler, any action or proceeding arising from or relating to this Agreement must be brought in a federal court in Pennsylvania or in state court in Pennsylvania, and each party irrevocably submits to the jurisdiction and venue of any such court in any such action or proceeding. The prevailing party in any action arising out of this Agreement shall be entitled to an award of its costs and attorneys’ fees. This Agreement may be amended only by a writing executed by Viddler. If any provision of this Agreement is held to be unenforceable for any reason, such provision shall be reformed only to the extent necessary to make it enforceable. The failure of Viddler to act with respect to a breach of this Agreement by Licensee or others does not constitute a waiver and shall not limit Viddler’s rights with respect to such breach or any subsequent breaches. This Agreement is personal to Licensee and may not be assigned or transferred for any reason whatsoever (including, without limitation, by operation of law, merger, reorganization, or as a result of an acquisition or change of control involving Licensee) without Viddler’s prior written consent and any action or conduct in violation of the foregoing shall be void and without effect. Viddler expressly reserves the right to assign this Agreement and to delegate any of its obligations hereunder.

[[Category:API]]
[[Category:Developers]]

Viddler Platform API v2

API Wrappers

Viddler has several wrappers available to use to make getting started with our data API easy!
Usage Instructions for these wrappers are located on their respective pages.

Supported Wrappers

phpViddler is a PHP class for Viddler’s Data API. Compatible with PHP 5.3 and higher.

Note: Your OpenSSL version will need to be compatible with TLS 1.2 .

Unsupported, Third-party or Experimental Wrappers

Please keep in mind that while we link to these wrappers, you are on your own if you run into trouble! Reach out to the developer of the wrapper you are using with any trouble or code improvements.

ViddlerSwift is an Apple Swift coding experiment for use in OS X or iOS projects. Does not currently handle binary upload tasks (uploading videos or manually uploading a thumbnail.)

viddler-ruby is a Ruby wrapper for the Viddler platform. This may be out-of-date.

How to Upload a Video

<?phpinclude('phpviddler.php');$user='YOUR USERNAME';$pass='YOUR PASSWORD';$api_key='YOUR API KEY';$callback_url='CALLBACK';$v=newViddler_V2($api_key);// Get a sessionid
$auth=$v->viddler_users_auth(array('user'=>$user,'password'=>$pass));$sessionid=$auth['auth']['sessionid'];// Call prepareUpload to retrieve the token and endpoint we need to use
$prepare_resp=$v->viddler_videos_prepareUpload(array('sessionid'=>$sessionid));$upload_server=$prepare_resp['upload']['endpoint'];$upload_token=$prepare_resp['upload']['token'];?><formmethod="post"action="<?=$upload_server?>"enctype="multipart/form-data"><inputtype="hidden"name="uploadtoken"value="<?=$upload_token?>"/><inputtype="hidden"name="callback"value="<?=$callback_url?>"/><label>Title:</label><inputtype="text"name="title"/><br/><label>Description:</label><inputtype="text"name="description"/><br/><label>Tags:</label><inputtype="text"name="tags"/><br/><label>File:</label><inputtype="file"name="file"/><br/><inputtype="submit"value="Upload"/></form>

Upload the video directly to that endpoint making sure to provide a callback URL.

The way the upload procedure works from here is this; the file gets uploaded to the endpoint you specified, all of the data that you sent (like title, tags, description) are also saved with the video, once the file upload is completed the video enters into the video encode queue on Viddler.com, and then the API will redirect back to the provided callback URL.

Code Examples

To the right there are examples of the upload procedures written in both PHP and Ruby.

All parameters being sent to the upload node must come before the file parameter. In other words, be sure to post uploadtoken and endpoint prior to the file, not after.

Authenticate an account. Returns a sessionid to be used with subsequent API methods. get_record_token set to 1 or true will provide a record token without needing to also call viddler.videos.getRecordToken.

sessionid values do expire after a set time. If the latest data from Viddler is required, make sure to call this before each “set” of data (pageload, group of actions). Otherwise caching the Viddler data is recommended.

Obtains encoding status. Send along a video_id to get status for all the files for that particular video only. This is an enhancement of our original, now deprecated, viddler.encoding.getStatus method.

The possible status codes are:

Code

Status

Description

-1

UNKNOWN

The system is unable to determine the status. This status code may appear if there is a problem during the upload or encode process.

0

NEWFILE

Newly created encode job.

1

WAITING

File successfully placed in the queue.

2

ENCODING

File is currently encoding.

3

CREATING_THUMBNAIL

File thumbnails are currently being created.

4

ENCODED

Encoding successful.

5

ERROR

Error was thrown during encoding.

10

CANCEL_ENCODE

User-initiated cancel. The system acknowledged the cancel request but is waiting to send or receive a response from the encode node.

11

ENCODE_CANCELLED

User-initiated cancel was successful.

15

ADMIN_CANCEL_ENCODE

This will appear if a Viddler staff member initiated a cancel (if there is a problem with the encode or during other troubleshooting.)

16

ADMIN_ENCODE_CANCELLED

Successful cancel by a Viddler staff member.

Parameters

sessionid - string; Required

video_id - string; Optional | The video_id can be obtained for a newly uploaded video by the information returned by the system after a completed upload. If a video_id is not included, this method will return the data for the last uploaded video.

Parameters

sessionid - string; Required

profile_#_bitrate - integer; Optional | Exchange the # for the actual id of the profile you’d like to change. For example, profile_8_bitrate for the 360p profile as of 2014. Bitrate in kilobits per second (kbps) and must be a value from the “allowed_bitrates” field.

use_source_for_playback - boolean; Optional | Deprecated, and not recommended, as the source must be a compatible H.264 .flv or .mp4 format video.

viddler.logins.add

Method Type:GET

Adds a new “login” account to a main user account. This type does not create a unique Viddler account, and can share either all videos or just a specific playlist.

Parameters

sessionid - string; Required

login - string; Required - The login you would like to update.

name - string; Required - The real name for the user(max 100 characters).