Truveo Video Search Developer Center

The Truveo Video Search AJAX API allows developers to access the Truveo video search engine using JavaScript and DHTML. Using this API, developers can build a variety of custom applications that feature video search results and functionality. The Truveo Video Search AJAX API is designed to work in most modern web browsers. Currently, this API will work in browsers that are at least as recent as the following versions: Internet Explorer 6.0, AOL Explorer 1.0, Firefox 1.0, Opera 8, Mozilla 1.7, Netscape 7.0, and Safari 2.0.

Accessing the API

To gain access to the Truveo Video Search AJAX API, you must first set up an API account. To create a new API account or view your existing API account, please consult the My API Account page. When you first create a new API account, you will be assigned a unique key, or Application ID. This Application ID is a string that uniquely identifies your organization's application and authorizes it to access the Truveo video search index.

Getting Started Using the AJAX API

To begin using the AJAX API, you will need to create an HTML page and host it on your web server. To enable access to the AJAX API in your application, you will first need to import the AJAX API JavaScript library into your web page. This can be done by placing the following <script> tag in the head of your document:

Additionally, in the body of your page you should include a container that will display the video search results retrieved using the AJAX API. The following code sample shows a complete HTML page with the JavaScript library imported and a <div> tag called 'results' included as a container for the search results:

Instantiating and Initializing the TruveoVideoSearch Object

With the AJAX API JavaScript library imported, you can now create an instance of the TruveoVideoSearch object, which is the JavaScript class that defines all of the attributes, methods, data objects and events of the AJAX API. To create an instance of this object, its constructor method must be called with a single argument, which is your assigned Application ID value. For example, the following code sample creates a new TruveoVideoSearch object with the Application ID '1x1jhj64466mi12ia' and assigns this object to the variable TVS:

TVS = new TruveoVideoSearch('1x1jhj64466mi12ia');

For most applications, it is convenient to instantiate the TruveoVideoSearch object after the HTML page has finished loading. The easiest way to do this is to create a function that is called by the 'onload' event of the document body. For example, in the sample code below, we have created a function called 'handlePageLoad' which is attached to the 'onload' event in the <body> tag of the page.

<html>
<head>
<script type="text/javascript"
src="http://xml.truveo.com/TruveoVideoSearchAPIv3.js">
</script>
<script type="text/javascript">
var TVS = null;
function handlePageLoad() {
TVS = new TruveoVideoSearch('1x1jhj64466mi12ia');
}
</script>
</head>
<body onload="handlePageLoad();">
<div id="results"></div>
</body>
</html>

Note that, in the example above, the variable 'TVS' is defined in the global scope so that it will be accessible to all scripts in your document.

Before you can begin using the methods of the TruveoVideoSearch object, you must first initialize this object. This can be done by calling the 'initialize' method of the object as follows:

TVS.initialize();

This initialization method will initialize the state of the AJAX API, and in some cases, it will send an asynchronous request to the Truveo video search service to see if the current user is logged in to your application. When these initialization steps are complete, the TruveoVideoSearch object will fire the 'onload' event. Therefore, if you intend to invoke other methods of the TruveoVideoSearch object as soon as initialization is complete, it is best to do this after the 'onload' event has fired. To detect the 'onload' event of the TruveoVideoSearch object, a handler can be attached to this event as follows:

TVS.attachEvent('onload', 'handleVSLoad();');

In this case, the function 'handleVSLoad' has been attached to the the 'onload' event of the TruveoVideoSearch object, and it will be called when the initialization of this object is complete. Note that this handler should be attached before the 'initialize' method is called so that it will successfully be able to catch the 'onload' event of the TruveoVideoSearch object. With these changes, the 'handlePageLoad' function definition will now look like:

function handlePageLoad() {
        TVS = new TruveoVideoSearch('1x1jhj64466mi12ia');
        TVS.attachEvent('onload', 'handleVSLoad();');
        TVS.initialize();
}

Retrieving and Displaying Video Search Results

With the TruveoVideoSearch object initialized, all of the methods and features of the Truveo Video Search AJAX API are now available for use. For this example, let us assume that you would like to retrieve a set of video search results about the topic 'Madonna' as soon as the TruveoVideoSearch object has been initialized. This can be done by defining a method named 'handleVSLoad' that calls the 'getVideos' method of the TruveoVideoSearch object:

function handleVSLoad() {
TVS.getVideos('Madonna');
}

When this method is invoked, an asynchronous request will be sent to the Truveo video search service to retrieve videos that match the query term 'Madonna'. Since this request is asynchronous, any code that follows this request will be executed immediately - in some cases before the response is received from the Truveo video search service. When the response is received, the 'onupdate' event of the TruveoVideoSearch object will fire. Therefore, in order to display the search results returned in this response, it is necessary to first handle this 'onupdate' event. As discussed above, a handler can be attached to the 'onupdate' event of the TruveoVideoSearch object using its 'attachEvent' method as follows:

TVS.attachEvent('onupdate', 'handleUpdate();');

In this case, the function 'handleUpdate' has been attached to the 'onupdate' event, and it will be called every time a response is received following a call to the Truveo video search service. To display the search results in the body of your web page, this function should define the necessary logic for formatting the information in the response for presentation in the body of your web page. As a simple example, the code below generates HTML that displays the title of every video returned in the search results and then writes it into the container <div> tag called 'results':

function handleUpdate() {
        var theHTML = '<h1>Hello World</h1>';
        for (var i=0; i < TVS.VideoSet.totalResultsReturned; i++) {
                theHTML += "<div>"+TVS.VideoSet.Video[i].title+"</div>";
        }
        document.getElementById('results').innerHTML = theHTML;
}

As shown above, the title of each video is available in the 'VideoSet.Video[i].title' attribute of the 'VideoSet' data object of the TruveoVideoSearch object. Additionally, the number of search results returned is available in the attribute 'VideoSet.totalResultsReturned'. For a complete list of the data objects and the fields of information supported by these objects, please consult the AJAX API reference documentation.

We have now completed the steps required to build a simple web page that displays video search results using the Truveo Video Search AJAX API. Bringing it all together, the code for this simple web page should now look as follows:

<html>
<head>
<title>Hello World</title>
<script type="text/javascript" src="http://xml.truveo.com/TruveoVideoSearchAPIv3.js"></script>
<script type="text/javascript">
var TVS = null;
function handlePageLoad() {
        TVS = new TruveoVideoSearch('1x1jhj64466mi12ia');
        TVS.attachEvent('onload', 'handleVSLoad();');
        TVS.attachEvent('onupdate', 'handleUpdate();');
        TVS.initialize();
}
function handleVSLoad() {
        TVS.getVideos('Madonna');
}
function handleUpdate() {
        var theHTML = '<h1>Hello World</h1>';
        for (var i=0; i < TVS.VideoSet.totalResultsReturned; i++) {
                theHTML += "<div>"+TVS.VideoSet.Video[i].title+"</div>";
        }
        document.getElementById('results').innerHTML = theHTML;
}
</script>
</head>
<body onload="handlePageLoad();">
<div id="results"></div>
</body>
</html>

Click here to try out a functioning version of this simple AJAX application.

You are now ready to get started building applications using the Truveo Video Search AJAX API. To view some simple and sophisticated applications built using this API, please check out the application gallery. To see a full list of the methods, attributes, data objects and events supported by this API, please consult the AJAX API reference documentation.