Helping you help us help you

As I mentioned in a previous post, we've taken several measures to help differentiate legitimate API traffic from bad requests. To help us serve you better, I'm pleased to announce a new way for you to identify your request as harmful. Beginning today, please include the &evil=true parameter in your API requests if you're one of the bad guys.

How does this work in practice? Here's an example query which lets Google know that you're intending to use the API for nefarious purposes. This way, we can respond to your request in the appropriate manner as efficiently as possible.

Note: In order to encourage adoption as quickly as possible, we are requiring all bad requests to include the evil bit by the end of today, April 1.

Search Form and Results on Two Different Pages

One of the major advantages of an Ajax style search box is that users can perform their queries and get their results without leaving the page. However, some webmasters prefer that their users go to a separate results page after they enter a search. The Ajax search library supports this "two-page" use case as well, and since this is a question that we see from time to time we've set up a simple demo site.

To create this page we wrote a simple form in HTML and added JavaScript to add the "Google Custom Search" branding in the search box. View source to see all the details.

When the user submits the form, they are taken to a results page which has the following HTML structure:

    <div id="results">Loading...</div>

We then tell the search library to draw its search box and results in the div we just created:

        // Draw the control in content div
        customSearchControl.draw('results');

Since the user came to this page from our search form, their query terms are now part of the page URL, so all we need to do now is extract them and execute their query:

      function getQuery() {
        var url = '' + window.location;
        var queryStart = url.indexOf('?') + 1;
        if (queryStart > 0) {
          var parts = url.substr(queryStart).split('&');
          for (var i = 0; i < parts.length; i++) {
            if (parts[i].substr(0, 1) == 'q') {
              return unescape(parts[i].split('=')[1].replace(/\+/g, ' '));
            }
          }
        }
        return '';
      }

      // See the source code of the results page for full details.

      ...
  

        // Run a query
        customSearchControl.execute(getQuery());

There is one more optional setting that you might be interested in. The second page which we've just created contains a search box that will allow the user to perform searches on this same page. If you would prefer for the search box not to appear on this results page we can add the following HTML to the page:

    <input style="display:none" id="hidden-input" />

We hide the input box because we don't want the Ajax search library to render the usual query input box, just to show the results. We then tell the search library to draw its search box in the hidden input, making it invisible:

        // Set drawing options to use our hidden input box.
        var drawOptions = new google.search.DrawOptions();
        drawOptions.setInput(document.getElementById('hidden-input'));

        // Change the draw call to include our new options.
        customSearchControl.draw('results', drawOptions);

To see an example of a two-page search setup with a hidden query input, visit this page.

To learn more about the Google Custom Search API, read our documentation. If you run into any problems while setting this up, post your question in our discussion group or hop on our IRC channel.

Finding Images on a Specific Site

One feature of the AJAX Image Search API that you might find useful is the ability to retrieve only the images which are visible on a specific website. For example, you could add a search box that allows people to search through just the images on your own site or you could create a slideshow which shows images from your favorite site.

To specify a site, use the setSiteRestriction method on an ImageSearch object. Here is a simple example:

http://code.google.com/apis/ajax/playground/#site_restrict

We can do more than just provide a site-specific image search box, we could also use the search results in a unique way. For example, we could create a slideshow which shows images which match our desired keyword and appear on a specific site. For this example, let's create a simple slideshow that displays images from nasa.gov.

var imageIndex = 0;
var images;

function nextImage() {
 imageIndex++;
 if (imageIndex >= images.length) {
   imageIndex = 0;
 }

 var imageContainer = document.getElementById(
     'image-container');
 imageContainer.src = images[imageIndex].tbUrl;
}

function searchComplete(searcher) {
 if (searcher.results && searcher.results.length > 0) {
   var contentDiv = document.getElementById(
       'content-slideshow');
   contentDiv.innerHTML = '';

   var imageTag = document.createElement('img');
   imageTag['id'] = 'image-container';
   imageTag['src'] = searcher.results[imageIndex].tbUrl;
   images = searcher.results;

   contentDiv.appendChild(imageTag);

   // Switch to the next image every 5 seconds.
   setInterval("nextImage();", 5000);
 }
}

function slideshowOnLoad() {
 var imageSearch = new google.search.ImageSearch();
 imageSearch.setSiteRestriction('nasa.gov');
 imageSearch.setSearchCompleteCallback(
     this, searchComplete, [imageSearch]);
 imageSearch.execute('supernova');
}

google.setOnLoadCallback(slideshowOnLoad);

In the above samples, there are three lines I'd like to call your attention to. The first line to note is the imageSearch.execute at the bottom, here we've entered the keywords that our slideshow images should be related to. Next we restrict the site to nasa.gov using imageSearch.setSiteRestriction. Lastly, we call setInterval once we receive the results of our search for images. The setInterval call tells the browser to run our nextImage function every five seconds.

Here are the two samples we've talked about in action:

The site restriction can also include a path within a website. For example you could do setSiteRestriction(
'http://www.flickr.com/photos/<username>') to search the photos that have been posted by a particular user on flickr.

To learn more about some other neat features of the AJAX Image Search API take a look at our code playground samples and documentation. For questions on this and other topics, drop us a line in the discussion group.