Getting Started With Truveo...

To paraphrase the greatest philosopher of the 20th century, Yogi Bera, “you better be careful if you don’t know what you’re looking for, because you might not find it”. With all of the resources available on the Internet, it’s become impossible to find anything without a good search engine. Last week AOL relaunched Truveo.com – a one stop place to search and browse the millions of videos available on the Internet today. Truveo searches metadata associated with video hosted around the Internet, producing some of the best video search results available.

What I found exciting, as a developer, was the full-featured API provided with Truveo. Offering XML, Ajax, Flash, and Ruby APIs – developers have a wide variety of ways to access Truveo’s searching mechanism.

I spent some time creating a very basic Mac OS X Dashboard Widget that utilizes the Truveo Ajax API interface. Since Dashboard Widgets are really standalone Web 2.0 applications – integrating the Truveo Ajax API was a snap!

Before you can utilize Truveo as a developer, you must have an API account. This simply associates your AOL userid with a key that provides access to Truveo services. This key must be used by your application when it initializes access to Truveo. The key does limit the number of Truveo queries to 10,000 per day. You can create your API account here: developer.truveo.com/APIMyAccount.php

To create my basic Dashboard widget – I used Apple’s Dashcode to jumpstart my development (it’s important to note that the Dashcode beta has now expired – but is accessible to Premier or Select Apple Developer Connection members). Even though I used Dashcode – the techniques to integrate Truveo I’ll review here can be utilized however you develop Dashboard Widgets.

As I indicated previously, Dashboard Widgets are mini Web 2.0 applications – with their programmatic interface coming from Javascript – so the Truveo Ajax API is a perfect fit!

In the main widget HTML page you’ll need to make sure you include the Truveo Javascript library as follows:

<script type="text/javascript" src="http://xml.truveo.com/TruveoVideoSearchAPIv3.js"></script>

The Dashboard Widget I created had a standard and configuration (back) view that you can see here:

You can enter a search term in the searchfield, and the widget will initiate a request with the Truveo search engine, displaying the titles that match in the scrollarea below. In the widget configuration you can filter your searches such that only certain file types are returned (if none are checked all types are returned).

To gain access to Truveo from your application you must create a TruveoVideoSearch object. To create a TruveoVideoSearch object you’ll need the API account key you created earlier. You can view the TruveoVideSearch object reference here: developer.truveo.com/AJAXAPIDocumentation.php

I added an onLoad event for my widget to create the object:

function myLoadHandler(event) 
{
     // Don’t forget to include your API key in place of YOUR_API_KEY
     // in the TruveoVideoSearch constructor! 
     TVS = new TruveoVideoSearch('YOUR_API_KEY');
     TVS.attachEvent('onupdate', 'handleUpdate();');
     TVS.initialize();
}

It’s important to note that when searches are performed the results are returned asynchronously – so you must associate a Javascript function with the onupdate event of the TruveoVideoSearch object to handle the returned results. I’ll show you the code for handleUpdate shortly. Before we can handle the search results – we must first trigger the search. I created an onChange event for the Dashcode searchfield object – myChangeHandler:

function getSearchFilter() 
{
     // Access the configuration checkboxes objects
     var checkWin = document.getElementById("checkWin");
     var checkReal = document.getElementById("checkReal");
     var checkQT = document.getElementById("checkQT");
     var checkFlash = document.getElementById("checkFlash");
     var checkAOLHiQ = document.getElementById("checkAOLHiQ");
     var searchFilter = " ";

     // append to search filter string based on the checked status of each check box 
     // check boxes...	
     if(checkWin.checked) {
          searchFilter += "format:win ";
     }
     if(checkReal.checked) {
          searchFilter += "format:real ";
     }
     if(checkQT.checked) {
          searchFilter += "format:qt ";
     }
     if(checkFlash.checked) {
          searchFilter += "format:flash ";
     }
     if(checkAOLHiQ.checked) {
          searchFilter += "format:hi-q";
     }
	
     // return the search filter string created
     return searchFilter;
}

function myChangeHandler(event) 
{
     // retrieve the string entered in the search filed text box
     var s = document.getElementById("searchfield");

     // call the asynchronous getVideos method
     TVS.getVideos(s.value + " " + getSearchFilter());
}

The Truveo API provides search filters to limit video type, runtime, quality, bitrate, format, site, days_old, and file_size. You can read more about the search filters here: developer.truveo.com/UsingFilters.php. I chose to illustrate the format search filters. The getSearchFilter function creates the filter parameters to limit the video formats returned by the search.

The getVideos method asynchronously returns the search results – which will trigger the handleUpdate function. In this basic example I simply populate the widget scrollArea with the titles returned by the query. You can see the handleUpdate implementation here:

function handleUpdate() {
     // access the scroll area object...
     var content = document.getElementById("scrollArea").object.content;

     // loop through the result set - append each item to the resultText string
     var resultText = "";
     for (var i=0; i < TVS.VideoSet.totalResultsReturned; i++) {
         // make sure we append returns \n after each title so each appears on its own line...
          resultText += TVS.VideoSet.Video[i].title+"\n";
     }

     // put the result string in the scroll area
     content.innerText = resultText;

     // refresh the scroll area so the new contents are displayed...
     document.getElementById("scrollArea").object.refresh();
}

I think you’ll find the Truveo API a powerful mechanism for providing comprehensive video searching in your Web applications! I hope this gets you excited about the Truveo API – you can start exploring more on your own at the Truveo Developer Center, developer.truveo.com

Next week we’ll continue to explore more capabilities of the Truveo API in our Dashboard widget.

Are you working on any Mac OS X applications or widgets that integrate any of the AOL APIs? If so – I’d love to hear about your projects!