1. Ensemble Video Support
  2. User Guides
  3. Integrations

Simple Publishing API v1

Follow
Avatar
Roman Markowski

Contents

Overview

The simple publishing API is a REST-based web service for retrieving data from the Ensemble Video application. It is inteded to be used by third party web sites and services to interact with the Ensemble Video application. The API can return data in three different formats: XML and JSON (Java Script Object Notation), JSONP (implementation of JSON that allows cross-domain data transfer - v3.2.1 and above). You can use any programming language that supports XML/HTTP transfer and can parse either XML or JSON. The first version of the API supports several features:

  • Listing videos in a particular web destination: This includes video metadata and thumnails so that video lists can be created and published on an external web sites.
  • Showing invidividual video information: This includes all video metadata, video encodings, previews/thumnails, attachments, links, credits, etc.
  • Listing categories in a particular web destination: This includes information related to each category in a particular web site.
  • Extensive parameters to query and filter the data to be returned

Since the API implements the REST protocol, our API calls follow typical REST conventions. This includes the REST verbs (list, show,add,edit). The most recent version of the API supports the "list" and "show" verbs only:

  • List - used to list get a list of records such as listing of videos in a web destination
  • Show - used to get an individual record such an single video

A REST procedure call is a very structured HTTP call that will return the type of object specified in the call. Below are the parts of an API call and an example that returns the XML for all videos in a web desination:

Example API Call

http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/4M2akAsn2EGhYH9edW8YSA?resultsCount=10

  1. API Root - http://cloud.ensemblevideo.com/ensemble/app/simpleapi
    Base URL that must be included to start the API call
  2. Data Object - /video
    The type of data you want to return (video or category)
  3. REST Verb - /list
    How you want the data to be returned (list or show)
  4. Return Format - .xml
    What type of data you want to return (XML or JSON(P))
  5. Data ID - /4M2akAsn2EGhYH9edW8YSA
    ID of the web destination or video
  6. API Parameters - ?resultsCount=10
    Parameters for the query. A full list can be found below .

API Parameters

Parameter Name Description Values (Default)
categoryID* categoryID obtained from Ensemble Video application Guid or ShortGuid (none)
categoryName text value of the category (this category must exist in the web destination you are querying against) String (none)
orderBy specifies the field name/attribute to order the query by String (ID field)
orderByDirection specifies sorting order; used in combination with the orderBy parameter String 'asc' or 'desc' ('asc')
pageIndex indicates current page in the results set you want to display Integer (0)
pageSize indicates how many content items to return per page Integer (20)
resultsCount max amount of records you want returned with your query Integer (all records)
searchString use this parameter for perform searches from your app String (none)
videoID* videoID obtained from Ensemble Video Application Guid or ShortGuid (none)
websiteID* websiteID obtained from Ensemble Video Application Guid or ShortGuid (none)

* ID fields can be called explicitly in API parameters or can be used as part of the base URI. The following calls produce the same result:

http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/4M2akAsn2EGhYH9edW8YSA
http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/?websiteID=4M2akAsn2EGhYH9edW8YSA

Examples

  • Get a list of videos in a particular web site

http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/4M2akAsn2EGhYH9edW8YSA

  • Get information for individual video

http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/show.xml/ic2w-dvGpEu5T5dB4DBeFQ

  • Get a list of 10 most recent videos

http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/4M2akAsn2EGhYH9edW8YSA?orderBy=videoTitle&orderByDirection=desc&resultsCount=10

  • Get a list of categories for a web site

http://cloud.ensemblevideo.com/ensemble/app/simpleapi/category/list.xml/4M2akAsn2EGhYH9edW8YSA

 

Types of Data

The current version of the API can return 3 distinct types of data:

  • A list of videos published in Ensemble Video
  • A list of categories used in Ensemble Video
  • Detailed video information

Each set of data can be filtered and sorted by using the API parameters specified below. However, since each type of data contains different information, here is a list of columns returned by each type:

  • The video list (without category constraint)
Field Name
videoID
videoDate
videoDescription
videoTitle
videoDuration
videoKeywords
thumbnailUrl
webSiteID
webSiteName
departmentID
departmentName
departmentWebSite
departmentLogo
  • The video list (with category constraint)
Field Name
videoID
videoDate
videoDescription
videoTitle
videoDuration
videoKeywords
thumbnailUrl
webSiteID
webSiteName
categoryID
categoryName
departmentID
departmentName
departmentWebSite
departmentLogo
  • The category list
Field Name
categoryID
categoryName
webSiteID
websiteName
departmentID
departmentName
departmentWebSite
departmentLogo
  • Detailed video information
Data returned for the individual content is contained in a complex type (XML) or a structure (JSON). Please see the XML example of data returned for the individual video.
Complex Type
departmentInformation
videoInformation
videoImages
videoEncodings
videoAttachments
videoLinks
videoGenres
videoRatings
videoStatistics
contentTypePlayers

Example Data

  • Video list in XML format 
<videos>
  <video>
    <videoID>e1P4G0MuCUeL0LTBz1xabQ</videoID>
    <videoDate>2008-07-10T13:20:13-04:00</videoDate>
    <videoDescription>One Small step for man video</videoDescription>
    <videoTitle>One Small Step for Man</videoTitle>
    <videoDuration>00:01:00</videoDuration>
    <videoKeywords/>
    <thumbnailUrl>http://demo.ensemblevideo.com/ensemble/app/files/1bf8537b-2e43-4709-8bd0-b4c1cf5c5a6d/thumb/OneSmallStepForMan_thumb05.jpg</thumbnailUrl>
    <webSiteID>OJkxH-bafkaKYRmJo11EQA</webSiteID>
    <webSiteName>Demo</webSiteName>
    <departmentID>tpgodoXPnUKvWOA8eg7HYQ</departmentID>
    <departmentName>Demo Department</departmentName>
    <departmentWebSite>http://demo.ensemblevideo.com</departmentWebSite>
    <departmentLogo/>
  </video>
  <video>
    <videoID>pWy7JqK0WUWvq61MQXTFIw</videoID>
    <videoDate>2008-05-28T16:13:39-04:00</videoDate>
    <videoDescription>Test video upload</videoDescription>
    <videoTitle>Test Video - Grizzly Bear!!</videoTitle>
    <videoDuration>00:01:00</videoDuration>
    <videoKeywords/>
    <thumbnailUrl>http://demo.ensemblevideo.com/ensemble/app/files/26bb6ca5-b4a2-4559-afab-ad4c4174c523/thumb/Bear - Copy - Copy_thumb02.jpg</thumbnailUrl>
    <webSiteID>OJkxH-bafkaKYRmJo11EQA</webSiteID>
    <webSiteName>Demo</webSiteName>
    <departmentID>tpgodoXPnUKvWOA8eg7HYQ</departmentID>
    <departmentName>Demo Department</departmentName>
    <departmentWebSite>http://demo.ensemblevideo.com</departmentWebSite>
    <departmentLogo/>
  </video>
</videos>
  • Video list in JSON format 
var _xsajax$transport_status = 200;
var data = { videos: {
	video: [
	{
		"departmentID": "tpgodoXPnUKvWOA8eg7HYQ",
		"departmentLogo": null,
		"departmentName": "Demo Department",
		"departmentWebSite": "http://demo.ensemblevideo.com",
		"thumbnailUrl": "http://demo.ensemblevideo.com/ensemble/app/files/1bf8537b-2e43-4709-8bd0-b4c1cf5c5a6d/thumb/OneSmallStepForMan_thumb05.jpg",
		"videoDate": "2008-07-10T13:20:13-04:00",
		"videoDescription": "One Small step for man video",
		"videoDuration": "00:01:00",
		"videoID": "e1P4G0MuCUeL0LTBz1xabQ",
		"videoKeywords": null,
		"videoTitle": "One Small Step for Man",
		"webSiteID": "OJkxH-bafkaKYRmJo11EQA",
		"webSiteName": "Demo"
	}
	,
	{
		"departmentID": "tpgodoXPnUKvWOA8eg7HYQ",
		"departmentLogo": null,
		"departmentName": "Demo Department",
		"departmentWebSite": "http://demo.ensemblevideo.com",
		"thumbnailUrl": "http://demo.ensemblevideo.com/ensemble/app/files/26bb6ca5-b4a2-4559-afab-ad4c4174c523/thumb/Bear - Copy - Copy_thumb02.jpg",
		"videoDate": "2008-05-28T16:13:39-04:00",
		"videoDescription": "Test video upload",
		"videoDuration": "00:01:00",
		"videoID": "pWy7JqK0WUWvq61MQXTFIw",
		"videoKeywords": null,
		"videoTitle": "Test Video - Grizzly Bear!!",
		"webSiteID": "OJkxH-bafkaKYRmJo11EQA",
		"webSiteName": "Demo"
	}
]}};
  • Video Details in XML format 
<videos>
  <departmentInformation>
    <departmentID>tpgodoXPnUKvWOA8eg7HYQ</departmentID>
    <departmentName>Demo Department</departmentName>
    <departmentLogo/>
    <departmentWebSite>http://demo.ensemblevideo.com</departmentWebSite>
  </departmentInformation>
  <videoInformation>
    <videoID>52G4RwAa-0SYZDrlGNFD1g</videoID>
    <primaryTitle>UB Paints</primaryTitle>
    <abstract>UB in the community</abstract>
    <genre>6bb95d8c-572b-46c2-8448-2fba237f65b4</genre>
    <keywords>UB Paints</keywords>
    <duration>00:02:00</duration>
    <dateProduced>2008-06-23T00:00:00-04:00</dateProduced>
    <dateAdded>2008-06-23T10:13:39-04:00</dateAdded>
    <dateUpdated>2008-06-23T11:20:41-04:00</dateUpdated>
    <copyright/>
    <isPublished>true</isPublished>
  </videoInformation>
  <videoImages>
    <imageUrl>http://demo.ensemblevideo.com/ensemble/app/files/47b861e7-1a00-44fb-9864-3ae518d143d6/selectedImages/UB_PAINTS_FINAL_for_web_thumb05.jpg</imageUrl>
    <imageType>Preview</imageType>
  </videoImages>
  <videoImages>
    <imageUrl>http://demo.ensemblevideo.com/ensemble/app/files/47b861e7-1a00-44fb-9864-3ae518d143d6/thumb/UB_PAINTS_FINAL_for_web_thumb05.jpg</imageUrl>
    <imageType>thumb</imageType>
  </videoImages>
  <videoEncodings>
    <videoID>47b861e7-1a00-44fb-9864-3ae518d143d6</videoID>
    <departmentID>762898b6-cf85-429d-af58-e03c7a0ec761</departmentID>
    <videoSourceID>48e843ee-e756-4bbe-ac16-84aff76a285f</videoSourceID>
    <videoSourceTypeID>1</videoSourceTypeID>
    <encodingID>115da45f-b63c-44b9-a01f-2914537993d5</encodingID>
    <relativePath>C:\Inetpub\wwwroot\videos</relativePath>
    <absolutePath>http://demo.ensemblevideo.com/videos</absolutePath>
    <fullFilePath>http://demo.ensemblevideo.com/videos/UB_PAINTS_FINAL_for_web.mov</fullFilePath>
    <bitRate>0</bitRate>
    <departmentBandwidthLabelID>9e7a1f45-d1be-4503-80c5-0a6aab8b3a14</departmentBandwidthLabelID>
    <bandwidthDescription>High Bandwidth</bandwidthDescription>
    <dimensions>Select</dimensions>
    <fileName>UB_PAINTS_FINAL_for_web.mov</fileName>
    <videoSize>11 MB</videoSize>
    <uploadManual>Upload</uploadManual>
    <md5Hash>f2cb0d6deadf7c5e418d5a2582220420</md5Hash>
    <videoFormat>video/quicktime</videoFormat>
    <videoFormatIconImage>http://demo.ensemblevideo.com/ensemble/app/images/video-quicktime.gif</videoFormatIconImage>
    <useEmbeddedPlayer>false</useEmbeddedPlayer>
  </videoEncodings>
  <videoAttachments>
    <name>UB Paints</name>
    <url>http://demo.ensemblevideo.com/ensemble/app/files/47b861e7-1a00-44fb-9864-3ae518d143d6/attachments/UB_PAINTS_FINAL_for_web.mov</url>
    <format>mov</format>
    <type>video/quicktime</type>
    <typeIconImageUrl>http://demo.ensemblevideo.com/ensemble/app/images/video-quicktime.gif</typeIconImageUrl>
    <size>11 MB</size>
    <description/>
  </videoAttachments>
  <videoAttachments>
    <name>UB Paints</name>
    <url>http://demo.ensemblevideo.com/ensemble/app/files/47b861e7-1a00-44fb-9864-3ae518d143d6/attachments/UB_PAINTS_FINAL_for_web.mov</url>
    <format>mov</format>
    <type>video/quicktime</type>
    <typeIconImageUrl>http://demo.ensemblevideo.com/ensemble/app/images/video-quicktime.gif</typeIconImageUrl>
    <size>11 MB</size>
    <description/>
  </videoAttachments>
  <videoLinks/>
  <videoCredits/>
  <videoGenres>
    <genreName>Documentary</genreName>
  </videoGenres>
  <videoRatings/>
  <videoStatistics>
    <totalViews>8</totalViews>
    <totalUsers>3</totalUsers>
    <averageDailyViews>4</averageDailyViews>
    <averageRating>0</averageRating>
    <numberOfRatings>0</numberOfRatings>
  </videoStatistics>
  <contentTypePlayers>
    <imageUrl>http://demo.ensemblevideo.com/ensemble/app/images/contentTypePlayers/getQuickTimePlayer.gif</imageUrl>
    <downloadUrl>http://www.apple.com/quicktime/download</downloadUrl>
  </contentTypePlayers>
</videos>

Tips and Tricks

Integrating the Ensemble Video Player

When building your own video site, it can be very cumbersome to build out your own player. Below is an example of how you could use the Ensemble Video player by using a mash-up of the HTML/JS video embed code, and the Ensemble Video API.

You can use an API call to get the contentID (also known as videoID). From there you can write a script to build out the embed code. You would just take the appropriate contentID and insert it in the proper place for the script tag. Below is a template example of how you might insert our player into your page. Simply replace the placeholder values with your Ensemble Server and ContentID. That video should now play on your site, using our player.


<div id="ensembleEmbeddedContent_{YOUR CONTENT ID}" class="ensembleEmbeddedContent" style="width: 640px; height: 390px;">

 

<script type="text/javascript" src="{YOUR ENSEMBLE SERVER}/app/plugin/plugin.aspx?
contentID={YOUR CONTENT ID}&useIFrame=true&embed=true&displayTitle=false&startTime=0&autoPlay=false&
hideControls=false&showCaptions=false&width=640&height=360"></script>

</div>

The advantages to using this are that we do automatic client checking and present an HTML 5 compatible player when necessary and possible.

Conclusion

There is a lot you can do with our API and publishing tools. If you need further assistance with the API or have any other questions about our system, please contact us at techsupport@ensemblevideo.com

0 out of 0 found this helpful
Newsletter Sign-Up

Articles in this section

See more