File Under: APIs, JavaScript

Add a Google Search Box to Your Site

Unless you’re incredibly handy at writing complex algorithms, building a search engine for your website is pain. And in the end, yours probably isn’t going to be that great, even after all your hard work. So why bother? Especially when there’s already a reasonably popular search engine by the name of Google — maybe you’ve heard of it? — that’s perfectly willing to handle the job for you.

The Google Search API is not only really good at searching, since it accesses the Google index, but it’s also really easy to use.

The potential for search-based mashups is nearly limitless, too. But in order to learn how it works, we’ll confine ourselves to a much more common use case — a site-specific search engine for your blog.


Contents

  1. Getting Started
    1. Implementing The Basic Search Engine
  2. Site Specific Search Engine
  3. Where to go From Here

Getting Started

The first step is to get a Google Search API. Just login to your Google account and head over the application page. Tell Google the domain where you’ll be using the Search API, then copy and paste your key. We’ll need it in just a minute.

First, just to ensure there’s no confusion, the only search API from Google uses Ajax. There was an older SOAP-based API, but sadly, that’s no longer available. You might still run across a few SOAP-based implementations since Google hasn’t shut it down, but it doesn’t hand out new keys.

Tip: The other thing to keep in mind is that if you’re launching a new site, the site-specific results won’t exist, since Google probably hasn’t crawled the URL yet. If you don’t have one, set up a Google Webmaster account and tell Google about your site by creating a sitemap. That should speed up the indexing process, though you will likely still have to wait a few days before a Google search returns anything useful.


Implementing The Basic Search Engine

The first thing to do is open up your site template and add this line to the head tags:

<script src="http://www.google.com/uds/api?file=uds.js&v=1.0&key=YOURKEYHERE" type="text/javascript"></script>

Paste in that API key you generated earlier and you’re ready to go. For now we’re going to write all our code in the page <head> tags. But if you end up with a long and complex script, it’s a better idea to break it out into its own file.

Next, add this to the <head>:


<script language="Javascript" type="text/javascript">

 //<![CDATA[


     // Create a search control

     var searchControl = new GSearchControl();

     // create a search object

     searchControl.addSearcher(new GwebSearch());

     // tell Google where to draw the searchbox

     searchControl.draw(document.getElementById("search-box"));

   }

   GSearch.setOnLoadCallback(OnLoad);

  //]]>

</script>

What we’ve done here is create a function that fires up when the page loads and creates a new GSearchControl object, which is a text input box and a search button. There’s also a little “Powered by Google” badge that will appear. We then create a searcher. In this case we’re just using a normal GwebSearch, which mimics the Google homepage.

Other options include video search, image search, blog search and several other of Google’s specialized search engines. For more details check out Google’s search documentation.

Once we have the object initialized and the type of search set, we have to tell Google where to draw the object. In this case, we’ll use a <div> with an id of “search-box,” so add this code in the body of your HTML file wherever you want the box to appear:

<div id="search-box">

</div>

Your users can now search Google without leaving your page. But that’s not exactly what we want. Read on to find out how we can limit the search to just your site.

Site Specific Search Engine

To restrict the results to just your domain, we need to create a site restriction. To do that we’re going to change this line:

searchControl.addSearcher(new GwebSearch());


To this:

var siteSearch = new GwebSearch();

siteSearch.setUserDefinedLabel("YourSite");

siteSearch.setUserDefinedClassSuffix("siteSearch");

siteSearch.setSiteRestriction("example.com");

searchControl.addSearcher(siteSearch);

Just fill in your site name and URL and you’re done. Give it a shot and you should see results limited to your domain — assuming Google has indexed it already.

Tip: You can string together as many of these site searches as you’d like and use setUserDefinedClassSuffix to add a different class to each domain. This makes it possible to do some fancy CSS work too, like color-coding your results by domain.

You can also create a search using a custom search engine if you have one defined. See the Search Docs for more details.


Where to go From Here

We’ve really just scratched the surface of what you can do with the Ajax Search API, so definitely read through the documentation and have a look at some of the examples. Mashup potentials abound — especially when using some the specialized search engines like local search or video.

Other options include the ability to control most of the look and feel via stylesheets, the ability to search Google Books to find quotes for your blog and more.

Tip: If this is just too much code (Aw, come on, really?) you can always use the handy Ajax Search Wizards to generate some cut and paste code that will perform basic searches.