jQTubeUtil - jQuery YouTube Search Utility v0.9.0 / Sept 11, 2010

Overview

I usually write a blurb here about why I created this and what its useful for, but this time I'm just going to keep it simple.

What is jQTubeUtil?

» A JSON-based YouTube Search utility.

What can it do?

» Search YouTube using keywords
» Search YouTube's standard feeds
» Fetch a specific YouTube video
» Get Autocomplete suggestions for YouTube

Why would I want to use it?

» Search YouTube FAST
» Get up and running with basic YouTube searches in no time
» Integrate YouTube into your site!
» Play with a friendly response of YouTubeVideo objects

Show me something

Gladly... Check out some examples

Quick Start Guide

 
1     Get an API Key

In order to utilize the YouTube GDATA API, you need to get a developer key.
To do so click on the following link: http://code.google.com/apis/youtube/dashboard/. Sign up for a key tied to your particular application.
Copy the API Key to your clipboard, as you will need it to init jQTubeUtil.

 
2     Import the jQTubeUtil

<script type='text/javascript' src='{your_path_to}/jQuery.jQTubeUtil.js'></script>
			

 
3     Initialize jQTubeUtil
! (Do this after the import, but before any calls are made)

<script type="text/javascript">
	jQTubeUtil.init({
		key: "[insert your key here]",
		orderby: "viewCount",  // *optional -- "viewCount" is set by default
		time: "this_month",   // *optional -- "this_month" is set by default
		maxResults: 10   // *optional -- defined as 10 results by default
	});
</script>
			

 
4     Decide on a search you want to perform

Free Text Search

jQTubeUtil.search("[keywords]", callbackFunction);  // basic: just specify the callback function 
jQTubeUtil.search(parametersObject, callbackFunction);  // advanced: fine tune the search 
			

Standard Feed Search

				
jQTubeUtil.mostViewed(callbackFunction);  // basic: just specify the callback function 
jQTubeUtil.mostViewed(parametersObject, callbackFunction);  // advanced: fine tune the search 

jQTubeUtil.mostRecent(callbackFunction);  // basic: just specify the callback function 
jQTubeUtil.mostRecent(parametersObject, callbackFunction);  // advanced: fine tune the search 

jQTubeUtil.mostPopular(callbackFunction);  // basic: just specify the callback function 
jQTubeUtil.mostPopular(parametersObject, callbackFunction);  // advanced: fine tune the search 

jQTubeUtil.topRated(callbackFunction);  // basic: just specify the callback function 
jQTubeUtil.topRated(parametersObject, callbackFunction);  // advanced: fine tune the search 

jQTubeUtil.topFavs(callbackFunction);  // basic: just specify the callback function 
jQTubeUtil.topFavs(parametersObject, callbackFunction);  // advanced: fine tune the search 

			

Single Video Fetch

jQTubeUtil.video(videoId, callbackFunction);
			

Autucomplete via Google Suggest

jQTubeUtil.suggest("[keywords]", callbackFunction);
			

 
5     Setup the appropriate callback

Free Text Search & Standard Feed Search

callbackFunction = function(response){ 
	var html = "";
	for(vid in response.videos){
		var video = response.videos[vid];
		html += "Video : " + video.title;
	}
	alert(html);
}
			

Single Video Fetch

callbackFunction = function(response){ 
	var html = "";
	var vid = response.videos[0];
	html = "Video : " + vid.title;
	alert(html);
}
			

Autocomplete via Google Suggest

callbackFunction = function(response){ 
	var html = "";
	for(sug in response.suggestions){
		var suggestion = response.suggestions[sug];
		html += "Suggested : " + 
	}
	alert(html);
}
			

 
6     Tune your search criteria

Free Text Search

The Free Text search can be simply passed a string argument, and it'll use the defaults when the jQTubeUtil was initialized. If, however, you want to specify more details in a specific search you can pass an object, and pass the string in as a parameter, "q".

The additional parameters you can override, are "time", "orderby" and "max-results". To simplify the selecting of time and orderby, the jQTubeUtil utility provides public getters - getTimes() and getOrders(). All you need to do is select which item of that you want, and pass it with the parametersObject. Max-results is a number and defines the max number of videos you want in the response.

parametersObject = {
	"q": "search query",
	"time": jQTubeUtil.getTimes()[pick an index],
	"orderby": jQTubeUtil.getOrders()[pick an index],
	"max-results": 20
}
			

Standard Feed Search

The three parameters you can override are "time", "orderby" and "max-results". Again, as detailed above, use jQTubeUtil's public getter methods for time.

parametersObject = {
	"time": jQTubeUtil.getTimes()[pick an index],
	"orderby": jQTubeUtil.getOrders()[pick an index],
	"max-results": 20
}
			

Defaults / Internals

If you haven't already, check out the YouTube Data API Protocol Documentation. This jQuery utility was written around it.

The jQTubeUtil utility is just a wrapper for the YouTube GDATA API. The GDATA API supports JSON requests, which is what the jQTubeUtil utilizes jQuery to take advantage of. The utility simply builds the URLs by providing a friendly interface to interact with both the search and the results, and sets up the appropriate methods to get you started as soon as you get your developer key.

The jQTubeUtil utility essentially treats objects passed in as request 'parameters'. The object represents the name-value pairs that makeup the request uri. The plugin's defaults are separated into two types: regular search defaults (Applicable to keyword based searches and standard feeds) --

var SearchDefaults = {
	"q": "",
	"orderby": jQTubeUtil.getOrders()[2],
	"time": jQTubeUtil.getTimes()[3],
	"max-results": 10
});


The core defaults, which cannot be modified, are passed into each request -

var CoreDefaults = {
	"key": "<the key that you pass in>",
	"format": 5, 
	"alt": "json",
	"callback": "?"
});


The autocomplete also has defaults, which cannot currently be modified -

var SuggestDefaults = {
	"hl": "en",
	"ds": "yt", 
	"client": "youtube",
	"hjson": "t",
	"cp": 1
});

Helpers

The jQTubeUtil's aim is to simplify searching YouTube. There are parameters that the YouTube API specifies and requires as options for particular request params. The two parameters that jQTubeUtil currently support retrieving the options out of, are "orderby" and "time". In an effort to simplify the selection process, the utility provides public getters to retrieve them so you can select an option.

"orderby" options

jQTubeUtil.getOrders() = ["relevance", "published", "viewCount", "rating"];

"time" options

jQTubeUtil.getTimes() = ["today","this_week","this_month","all_time"],

Methods

The jQTubeUtil object is a singleton. It has methods that you can use by passing callbacks along with params (if any).

Initialization

 jQTubeUtil.init({
	 key: "my key",
	 orderby: jQTubeUtil.getOrders()[#],
	 time: jQTubeUtil.getTimes()[#],
	 maxResults: #,
	 lang: "en"
 });
You must initialize the jQTubeUtil in order to make requests to YouTube.
» "key" is required. and is the developer API key for your app. (see above)
» "orderby", "time" and "maxResults" are optional. They pertain to the YouTube search defaults.
» "lang" is also optional and can be used

Search - Free Text & Standard Feeds

 jQTubeUtil.search("family guy",function(response){
	 /* The response */ 
 });

 jQTubeUtil.search({
	"q": "family guy",
	"time": jQTubeUtil.getTimes()[#],
	"orderby": jQTubeUtil.getOrders()[#],
	"max-results": 25
 },function(response){
	 /* The response */ 
 });
The basic search utilizes the defaults that were used upon initialization (defaults otherwise).
The response object is a collections of videos and metadata around the search that was performed.


The search method also has the ability for 'tuned' searches. "q" is imperitive, whilst the rest can be added at your desire.

Single Video Fetch

 jQTubeUtil.video("videoId",function(response){
	 /* The response object */ 
 });
You can get a particular video id by simply passing in the video id as a string. The response remains the same as all the other requests, however in the videos collection there is only a single video.

Autocomplete Suggestion

 jQTubeUtil.suggest("family guy", function(response){
	/*  response = { 
		suggestions:[], 
		searchURL: String 
		}  */
 });
Suggest returns an array of autocomplete suggestions as per an unofficially supported Google API.

Legal

MIT License

Basic Example of Search

jQTubeUtil.search(jQuery('[name=free_text_1]').val(), function(response){
	var html = "";
	for(v in response.videos){
		var video = response.videos[v]; // this is a 'friendly' YouTubeVideo object
		html += (parseInt(v)+1) + " : " + video.title + " <br/>";
	}
	jQuery("#basic_search_response_itemsPerPage").html(response.itemsPerPage);
	jQuery("#basic_search_response_searchURL").html(response.searchURL);
	jQuery("#basic_search_response_startIndex").html(response.startIndex);
	jQuery("#basic_search_response_totalResults").html(response.totalResults);
	jQuery("#basic_search_response_version").html(response.version);
	jQuery("#basic_search_response").html(html);
});


Example of searching the standard YouTube Feeds

jQTubeUtil[jQuery('[name=feed_selector] option:selected').val()](function(response){
	var html = "";
	for(v in response.videos){
		var video = response.videos[s]; // this is a 'friendly' YouTubeVideo object
		html += (parseInt(v)+1) + " : " + video.title + " <br/>";
	}
	jQuery("#feed_search_response_itemsPerPage").html(response.itemsPerPage);
	jQuery("#feed_search_response_searchURL").html(response.searchURL);
	jQuery("#feed_search_response_startIndex").html(response.startIndex);
	jQuery("#feed_search_response_totalResults").html(response.totalResults);
	jQuery("#feed_search_response_version").html(response.version);
	jQuery("#feed_search_response").html(html);
});


Example of fetching a particular YouTube video

jQTubeUtil.video("videoId", function(response){
	var html = "";
	var video = response.videos[0]; // this is a 'friendly' YouTubeVideo object
	html = /* personal show object function */;
	jQuery("#video_fetch_response").html(html);
});


Autocomplete Suggestions from Google Suggest

jQuery('[name=suggest_search_1]').keyup(function(){
	jQTubeUtil.suggest($(this).val(), function(response){
		var html = "";
		for(s in response.suggestions){
			var sug = response.suggestions[s];
			html += (parseInt(s)+1) + " : " + sug + " <br/>";
		}
		jQuery("#suggest_search_response_url").html(response.searchURL);
		jQuery("#suggest_search_response_length").html(response.suggestions.length);
		jQuery("#suggest_search_response").html(html);
	});
});



File details / download

v0.9.0

Production - 3.6kB ( Download )
Minified with Google Compiler

Development - 9.8kB ( Download )
Commented

Changelog

Next up..
» Regional search
» All Feeds

v0.9.0 - Sept 11, 2010

> Search YouTube via:
  • » Free Text, keyword based search
  • » Free Text, keyword based search with specified options
  • » Standard Feeds (option overloading enabled as well):
    • » Most Viewed, Recent, Popular
    • » Top Rated, Favorited
  • » Single VideoID
> Provide 'Friendly' YouTubeVideo object in response
> Method to search Google Suggest for Autocomplete/Typeahead and return array of suggestions

Frequently Asked Questions

What version of jQuery is jQTubeUtil dependent on?

jQuery 1.3.2+

Does jQTubeUtil need anything else?

As long as you have a Developer Key you should be all set.