Using the AOL API with ASP.NET: Part 1 - AOL Video Search | dev.aol.com

by Shawn Wildermuth
February 15, 2007

Introduction

On the internet today, video is king. If you don't believe me, turn on CNN and see how long you can go before you hear YouTube, GoogleVideo or one of the plethora of video-based websites mentioned. I bet it is not long. Most of the videos are the kind that used to fill your email box, but some are of great value to business and personal websites. To ride this video wave, you will want to integrate video into your own site. While most of us do not have the bandwidth or infrastructure to write a competitor to YouTube, it would be nice if you could add links to related videos on your site.

As seen in "Building a Simple AOL Video Search API Application Using Ajax," the AOL Video Search API is a powerful, robust tool for searching for videos located on the internet. In that article, Paul Sobocinski showed you how to use the Ajax AOL Video Search API. In this, the first of several articles, I will show you how to use the tools available on http://dev.aol.com in your own ASP.NET-driven websites. This first article is devoted to integrating AOL's Video Search into your ASP.NET website.

AOL Video Search XML API

ASP.NET is a server-based framework; therefore, we need a video search API that works for us on the server. For our needs, we will use the Video Search's XML API. This XML API is essentially a query string API that returns an XML result of our video search. To perform searches (just like from the Ajax API), you will need your own Application ID. For the examples in this article, I will be using YOURAPPID as the API key. You will need to replace this string with your actual Application ID before the example will work.

The XML API consists of an URL with several query string parameters. For example:

http://beta.searchvideo.com/apiv3?appid=YOURAPPID&method=truveo.videos.getVideos&query=kungfu%20baby

This URL contains the key pieces of the search API:

appid: Your Application ID that you get from AOL.
method: The API method to call. There are a number of different methods, but for this article we are using the simple video search API (called truveo.videos.getVideo).
query: The actual search query. This searches for "Kungfu Baby" (lower-cased and URL encoded).

There are more query parameters that we will delve into in our example, but at a minimum this is the form of the query you want to execute. When this query is executed, it returns an XML document that you can use to show the results of the video search.

ASP.NET

To show how you can integrate video search into an ASP.NET project, I will use a simple single-page ASP.NET website. Our web page should allow a user to search with a search phrase, and it supports paging the results. Before we get started, start up Visual Studio 2005 and create a new website. In the new website, open the .aspx file that was created for you. Add a TextBox and a Button so we can have the user enter in a search phrase. If you double-click the button, it should take to you an event handler for our new button. In that button, make a call to a new method that we will create called PerformSearch.

Now we need to create the PerformSearch method. In order to perform the search, we will need to actually make an HTTP request of the server. We will do this in two steps: constructing the URL for the search and executing the search. Inside our new method, create a string variable to hold both the appId and the method of the search API we are going to use. Next, create another string to hold search terms from the user and URL encode them to allow us to use them in our search. Then we can construct our search URL using these composite parts. Our method should now look like so:

void PerformSearch() 
{ 
  const string appId = "YOURAPPID"; // Your AppID here 
  const string method = "truveo.videos.getVideos"; 
  
  // Construct the Search and Search URL 
  string searchTerm = Server.UrlEncode(searchText.Value); 
  string requestUrl = string.Format("http://beta.searchvideo.com/apiv3?appid={0}&method={1}&query={2}",
    appId, 
    method, 
    searchTerm); 
}

Now we can execute the search based on our search request. To do this we will use the HttpWebRequest class (contained in the System.Net namespace). First we create an instance of the request using the HttpWebRequest.Create method. Once we have the instance we can request a response by calling the GetResponse method (which returns a WebResponse object). We can then retrieve a Stream from the WebResponse object like so:

// Perform an Synchronous Search 
HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create(requestUrl);
WebResponse response = req.GetResponse(); 
// The Stream of the Search Response Stream
strm = response.GetResponseStream();

Displaying the Results

Now that we have our search results in a stream, we need to show the results on our page. We could use a DataSource provider but because we are doing a server-to-server HTTP request, the built-in providers are not a good solution. In addition, we want to show some additional information on our page and manually dealing with the result is a better solution.

To allow us to show the results, go back to the web page and add a DataList. The DataList will allow us to display the results in a simple way and supports built-in column handling. To support more than one column, edit the properties of the DataList and set the RepeatColumns to "2" to specify that we want two columns. Next, switch the page editor to the Source of the page. Manually add an ItemTemplate element within the DataList. This will be the template for each of our results. Within the ItemTemplate, create a simple template for your results. Each result supports a number of different properties that we can bind to, but for this example we're just going to use:

<ItemTemplate>
  <div style="font-weight: bold"><%# Eval("Title") %></div>
  <a href='<%# Eval("videoUrl") %>' target="_blank">
     <img src='<%# Eval("thumbnailUrl") %>' height="100" border="0" />
  </a>
</ItemTemplate>

Now that we have our DataList set up and ready for data, we need to prepare the results. The response stream that we have contains the XML of the result. To make it easier to work with, we want to convert it into an object graph. The best way to do this is to use the XSD.exe tool that ships with the .NET framework SDK to generate classes based on the XSD of the result. To do this we need to first get a copy of the XSD that describes the results. To do so, follow these directions:

Add an App_Data directory to the project. (App_Data is a special directory for code to be compiled.)
Using a web browser, navigate to http://best.searchvideo.com/apiv3.xsd.
Save the resulting XSD file to the App_Code directory.

Next we want to generate the classes based on the XSD. We will use the XSD.exe tool to do this:

In the Start menu, under the Microsoft Visual Studio 2005\Visual Studio Tools directory, pick "Visual Studio 2005 Command Prompt."
Go to the App_Data directory where you saved the XSD file.
Run the XSD.exe tool like so (you can use vb for the /language if you are working in Visual Basic):

XSD.exe apiv3.xsd /language:cs /classes /namespace:Aol.Search.Video

Lastly, go back to your website project and you should see the new apiv3.cs (or .vb) file in the App_Code directory (if it doesn't appear, you can right-click on the directory and pick Refresh).

Running the XSD.exe command creates a new class file that mirrors the XSD in the Aol.Search.Video namespace. With this newly created class we can take the results of the search and use XML serialization to convert the resulting XML into an object graph. We can do this by creating an instance to the XmlSerializer class. When you instantiate the XmlSerializer, you specify the name of the object that it will serialize. In this it is the name of the Response class that we created with the XSD.exe tool. Next we can create an instance of our generated class (the Response class) by calling the Deserialize method of the XmlSerializer, like so:

// Deserialize the results into our XSD Generated Class 
XmlSerializer ser = new XmlSerializer(typeof(Aol.Search.Video.Response)); 
Response res = (Response)ser.Deserialize(strm);

Now we have an instance of our Response from the video search. It is easy then to use data binding to show the results of our search by binding to the results using the Video property of the VideoSet, which in turn is a property of our result:

// If there are results, then show them 
theDataList.DataSource = res.VideoSet.Video;
theDataList.DataBind();

Running the website now results in a functional video search page, as seen in Figure 1.

Figure 1. The working web page

In our example we are only using two pieces of information in our display of the results: the title and a thumbnail of the video. For each video found, the amount of data about the result is quite large. The documentation for the AOL Video Search API details all the properties you can use from the results.

The last thing we will do is add support for showing the number of results found. If you add a label to the page and call it numResultsLabel, we can set the text in the PerformSearch method. The result that was returned by the search has properties that describe information about the search that was performed. In this case we will want to show the total results found. We can do this by setting the Text property of our new label:

// Show the number of results
numResultsLabel.Text = string.Format("Found {0} result(s)",
res.VideoSet.totalResultsAvailable);

Now that we have encapsulated our functionality into the PerformSearch call, we could call it anywhere we need to. The completed PerformSearch method is shown below:

void PerformSearch()
{
  const string appId = "YOURAPPID"; // Your AppID here
  const string method = "truveo.videos.getVideos";

  // Construct the Search and Search URL
  string searchTerm = Server.UrlEncode(searchText.Value); 
  string requestUrl = string.Format("http://beta.searchvideo.com/apiv3?appid={0}&method={1}&query={2}",
    appId,
    method,
    searchTerm);

  // Perform an Synchronous Search
  HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create(requestUrl);
  WebResponse response = req.GetResponse();

  // The Stream of the Search Response
  Stream strm = response.GetResponseStream();

  // Deserialize the results into our XSD Generated Class
  XmlSerializer ser = new XmlSerializer(typeof(Aol.Search.Video.Response));
  Response res = (Response)ser.Deserialize(strm);

  // If there are results, then show them
  theDataList.DataSource = res.VideoSet.Video;
  theDataList.DataBind();

  // Show the number of results
  numResultsLabel.Text = string.Format("Found {0} result(s)",
    res.VideoSet.totalResultsAvailable);
}

Conclusion

This article should give you a taste of how you can integrate AOL's Video Search API into your own ASP.NET projects. Using these simple techniques should allow you to add videos to your web projects. The source code included with this project includes some advanced features like support for paging.

References

AOL Video Search: The Video Search API documentation
"Building a Simple AOL Video Search API Application Using Ajax": An introduction to the Video Search API
"Introducing XML Serialization": The MSDN documentation
"XML Schema Definition Tool (XSD.exe)": The MSDN documentation
Source code: The example project

Topic Centers

Using the AOL API with ASP.NET: Part 1 - AOL Video Search