English | Site Directory

Google AJAX APIs

Developer's Guide

Using Google's AJAX APIs

Table of Contents

Getting Started
Detailed Documentation
google.load
API Namespaces
API Versioning
Dynamic Loading New!
Available AJAX APIs New!

Getting Started

Google has a number of AJAX APIs you can use in your web pages with no server side code, like the the Maps API, the AJAX Search API, and the AJAX Feed API. To use any or all of them in your web pages, you need only include a single <script> tag at the top of your web page with your Google API key:

<script type="text/javascript"
src="http://www.google.com/jsapi?key=ABCDEFG"></script>

If you don't yet have a Google API key, you can sign up for an API key for free.

Once the Google AJAX APIs script is loaded, you specify the modules you want to use on your page with google.load:

<script type="text/javascript">
  google.load("maps", "2");
  google.load("search", "1");
</script>

The example above loads version 2 of the Maps API and version 1 of the AJAX Search API. After you call google.load, you can use all of the loaded modules in your web page. In addition, use google.setOnLoadCallback to register the specified handler function to be called once the document loads. Here is an example that puts it all together:

<html>
  <head>
    <script type="text/javascript"
src="http://www.google.com/jsapi?key=ABCDEFG"></script>
    <script type="text/javascript">
      google.load("maps", "2");
      google.load("search", "1");

      // Call this function when the page has been loaded
      function initialize() {
        var map = new google.maps.Map2(document.getElementById("map"));
        map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);

        var searchControl = new google.search.SearchControl();
        searchControl.addSearcher(new google.search.WebSearch());
        searchControl.addSearcher(new google.search.NewsSearch());
        searchControl.draw(document.getElementById("searchcontrol"));
      }
      google.setOnLoadCallback(initialize);
    </script>

  </head>
  <body>
    <div id="map" style="width: 200px; height: 200px"></div>
    <div id="searchcontrol"></div>
  </body>

</html>

Detailed Documentation

google.load

The Google AJAX APIs <script> tag loads a single method, google.load, which loads individual AJAX APIs. It has the following prototype:

google.load(moduleName, moduleVersion, optionalSettings)

moduleName is the name of the API (e.g., "maps" or "search"). The module name also serves as the namespace of the API once it is loaded.

version specifies the version of the API module, as described below. It is a required argument; you must always specify the version of the API you are using. If you are unsure of which version you want to use, you should use the version used in the documentation and examples for the API you are using.

optionalSettings specifies all optional configuration options for the API you are loading as a JavaScript object literal. For example, you can specify the Japanese language of the Maps API user interface with:

google.load("maps", "2", {"language" : "ja_JP"});
You can also specify not to load the default CSS for the API being loaded, as shown below: 
google.load("feeds", "1", {"nocss" : true});

These settings vary for each API. Currently, language is only supported by the Maps API, AJAX Search API and AJAX Feed API. nocss is only supported by the AJAX Search API and AJAX Feed API.

See the documentation for each API you are using for the full set of available options.

API Namespaces

The module name of an API is also its namespace. So symbols from the "maps" module are available under the namespace google.maps when the module loads. Existing Google AJAX APIs like the Maps API use a G prefix for all exported classes and constants. With this new naming convention, class names no longer have the G prefix, e.g., GMap2 becomes google.maps.Map2.

APIs that currently use the G prefix will continue to support both the new and old naming conventions. Future APIs will only be available with the google.moduleName namespace.

API Versioning

The second parameter of google.load is the version of the API, modeled after the versioning system originally used by the Google Maps API. Every AJAX API has a major version and revision number, of the form VERSION.REVISION. Every time an an AJAX API introduces new JavaScript, the revision number is incremented. So if the AJAX Search API is on version 2.23, and the team does an update, the new JavaScript would be version 2.24.

Our AJAX APIs are updated frequently, so to ensure stability, all of our AJAX APIs have an active stable version and test version. Every time a team introduces of a new API revision, e.g., 2.24, the previous revision, 2.23, becomes the stable version of the API. Version 2.24 is the test version. If you request version 2 of the API without a revision specified, you will automatically get the stable revision of the API, 2.23. To get the test version of the API, you can request version 2.24 explicitly, or you can use the special wildcard 2.x, which always refers to the test version of the API. Version 2.24 remains the test version until the next revision is pushed.

The usage model we encourage is:

  • Use the stable version of each API (e.g., 2) in production HTML.
  • Use the test version of each API (e.g., 2.x) on your development machines, and report any issues you find in the developer forum for that API. If many users encounter serious issues with a particular API revision, Google will revert or hold back the revision.

While you can technically request any older version of an API at any time, old versions of APIs are not officially supported. In many cases, server-side changes will require that you stop using old versions of the API. However, we will try to keep old versions of each API on our servers for long periods of time so that developers that depend on legacy versions of APIs have as much time to upgrade as possible.

Dynamic Loading New!

The AJAX API loader can be included dynamically on your website. This is useful if you don't need the API available when the page loads, e.g. when a user performs a search or some other action.

This is done by passing a callback option in the third parameter, as show below: 

function mapsLoaded() {
  var map = new google.maps.Map2(document.getElementById("map"));
  map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);
}

function loadMaps() {
  google.load("maps", "2", {"callback" : mapsLoaded});
}

When you call loadMaps(), it will load the Maps API and execute the mapsLoaded callback when the API is ready. Make sure the DOM is ready when you call google.load with the callback option because it will try to append an element to the DOM. Subsequent calls to load the Maps API will immediately execute the provided callback, so you don't have to worry about loading the same API more than once.

You can load the Google AJAX API loader dynamically by creating a script element and setting it's source to the same "http://www.google.com/jsapi?..." URL with an additional query callback parameter. The callback will be executed when the loader is ready. See the snippet below: 

function mapsLoaded() {
  var map = new google.maps.Map2(document.getElementById("map"));
  map.setCenter(new google.maps.LatLng(37.4419, -122.1419), 13);
}

function loadMaps() {
  google.load("maps", "2", {"callback" : mapsLoaded});
}

function initLoader() {
  var script = document.createElement("script");
  script.src = "http://www.google.com/jsapi?key=ABCDEFG&callback=loadMaps";
  script.type = "text/javascript";
  document.getElementsByTagName("head")[0].appendChild(script);
}

Available AJAX APIs

The following Google AJAX APIs are available: