AJAX APIs Blog

When we introduced this blog over four years ago, the term AJAX was only a year old, and Google had exactly one relevant API . Ajax has since become a mainstream part of the Web, and our family of APIs has grown. Like many growing families, we’ve accumulated a lot of cruft over the years, and have outgrown our first home. Time for some housekeeping.

API Documentation - Now easier to find and use
We’ve reorganized our documentation to make it easier to find what you’re looking for, based on what you want to do. We used to group our APIs based on technology - for instance, there were Google Data APIs and AJAX APIs. Now, you’ll see that each API has been given its own place, including its own documentation pages. This new documentation has been created from the ground up to provide a better experience for people coding against the APIs. We’ve also organized these more logically by product, such as moving the Book Search API into the Books family of APIs, and added many more samples to help you get started.

A fond farewell
In the spirit of consolidation, we’ll be retiring this blog in favor of the Google Code Blog. By concentrating on fewer blogs, we’ll be able to keep the blog fresher and help make sure that as wide an audience as possible is able to benefit from our posts. We’ll continue using tags, so that you can subscribe to your favorite APIs and focus on the content that most interests you (though we hope you’ll check in occasionally to see what new stuff you might be missing).

Show your support for the Code blog by hopping over to read about the new Google APIs console and Custom Search API, and also say good-bye to the Web and Local Search APIs, which are being deprecated. Full post here.

Posted by: Adam Feldman, Product Manager

When using any of the searchers available in the Search API, four results are returned by default. Historically, it has been possible to request a large set of eight results (or ten for filter Custom Search Engines), but that’s it. We understand that there are many use cases for this API, and some of them require a finer grain of control over the number of results displayed.

For instance, with the JavaScript API, you can use .setResultSetSize(1) or .setResultSetSize(6) in addition to using the enum to request a SMALL_RESULTSET or LARGE_RESULTSET. When using the RESTful interface, you can also use any integer from 1 to 8 with the rsz parameter.

With this addition, you can now request an arbitrary number of results, based on the exact number you need. By requesting only the results you’re going to show to the end-user, you can make your site or app more efficient. Also, this will control the cursor values that can be used to retrieve subsequent pages of results (and impact paging in the Custom Search element).

For more details, check out the documentation, and if you have any questions, stop by our IRC channel and support forum.

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.

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.

We enjoy featuring real-world applications that show how versatile the AJAX APIs can be. Below we're highlighting two very different apps and the developers who built them:

AroundMe
AroundMe is an iPhone application where the AJAX APIs are central to the user experience. Specifically, the app utilizes the Local Search API to enable users to find information about their surroundings. In the videos below, Marco Pifferi (the developer behind AroundMe) gives a demo of his app, his thoughts on using the AJAX APIs, and tips for integrating them in mobile apps.



Mibbit
Mibbit is a web-based chat application that uses the AJAX APIs to enhance the chat experience. The language APIs help users to translate their messages into a number of different languages. Mibbit also uses the Maps API and YouTube API to display embedded maps or YouTube videos if a user includes a Maps or YouTube URL in their chat. Jimmy Moore, creator of Mibbit, walks through Mibbit in his video below.



Do you have a great app that uses the AJAX APIs? Submit a video about it and we may feature it on this blog. Questions? Stop by our support forum or IRC channel.

The AJAX Search gadget for Blogger is now available to all users on Blogger.com. This gadget accesses a Custom Search Engine (CSE) that is created automatically for your blog and provides search results inline, with the look and feel of your blog. You can get all this with just a few clicks from the Blogger control panel.

One cool feature of the gadget is the 'Linked From Here' feature that searches the pages you've linked to from your blog posts. As you create new posts, we automatically update your search engine to include all the linked pages, as well as all the pages linked from your link lists and blog lists. Check out the gadget — the search results match the look and feel of your blog and show up inline, as shown in the screenshot below. You can click a button to dismiss the results when you are done, and go back to reading the current post.



If you are not using Blogger, you can still create something similar for your website using the Custom Search element (read more about this new element at the Custom Search blog).

As part of Tuesday's Google Code Labs announcement, the AJAX Search API became part of the graduating class. We're still working with our lawyerly team members to update our Terms of Use to include a 3-year deprecation policy. If you're curious what that policy will look like, take a look at Section 4.5 of the Visualization API terms -- it will be similar to that.

You'll see that an exception to the deprecation policy will be features marked "experimental." This label is for experimental features that the deprecation policy does not apply to and therefore they can be changed or removed in the future, even if the deprecation policy applies to the rest of the API. You may have seen in the AJAX Search API reference that we have a few such features already, so we wanted to make sure you knew which ones those were.

The current experimental features include all of Book Search and the "image type" restriction of Image Search. We've done our best to clearly mark all of these as experimental in the docs.

As always, please let us know if you have any questions or comments.

As recently announced, a new program was introduced today for Google Code Labs. We're proud that the AJAX Search API has already graduated from Labs, which demonstrates our long-term commitment to it.

Also part of that announcement was that the SOAP Search API will be retired on August 31st, 2009. It was deprecated in 2006, when we stopped accepting new developers for the API. Since then, it's been steadily declining in usage and we believe the majority of use cases are sufficiently handled by the more comprehensive AJAX Search API.

In many ways, this AJAX API is a superset of the SOAP API, providing access to local, news, image, and video search results, among others, in addition to web search. Therefore, we encourage SOAP developers to explore our documentation and consider migrating their applications.

Please keep in mind that the AJAX APIs exist for the benefit of end-users; several of their features and usage guidelines are designed with them in mind. For instance, each search performed with the API must be the direct result of a user action. Automated searching is strictly prohibited, as is permanently storing any search results. Please refer to the Terms of Use for more detail.

And for developers new to the AJAX Search API, don't forget to check out our discussion group, a good resource if you have questions or need more help. Welcome aboard!

Today we are launching a new extension to the AJAX Search API, a Google News-based element. This element embeds a news slideshow on your site, letting your users see headlines and previews from Google News based on queries that you've selected. Here is an example of the NewsShow in action:

It couldn't be easier to add this to your site. Simply include this iframe:

<iframe src="http://www.google.com/uds/modules/elements/newsshow/iframe.html?format=300x250"
        frameborder="0" width="300" height="250"
        marginwidth="0" marginheight="0">
</iframe>

The element comes in two standard sizes: 728x90 and 300x250.

Adding a NewsShow to your site in this way allows you to customize its shape and content with URL arguments. Simply input your parameters into our wizard and we'll build the code for you. Or, for greater control over the NewsShow's look and feel, you can call the classes directly. Check out the documentation for details and the Code Playground to try your hand at customizing.

As always, let us know what you think in the Google AJAX API developer forum.

Note: Earlier this evening a reader pointed out a typo in the iframe snippet which has since been corrected.