Google has a number of AJAX APIs that you can use in your web pages with no
server side code, including 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>
google.setOnLoadCallback is used as a helper for
window.onload, which only happens once, when the document is
loading. Therefore, for dynamic loading of the API (such as after user
interaction), google.load with the callback option
should be used instead (see below).
google.loadThe 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"});
You can also specify not to load the default CSS for the API being loaded, as shown below:
google.load("feeds", "1", {"nocss" : true});
Some of the possible options are:
callback: The function to call once the script has loaded. If using the
Auto-loading feature, this must specify a function name, not
a function reference.language: The language in which to localize the API or API's UI controls.
This is specified as a ISO639 language code.nocss: A boolean that tells the API whether to load
any style sheets typically associated with its controls. A developer
might set this to true if he was completely overriding all
of the loaded CSS and wanted to avoid the unnecessary load.packages: An array of strings specifying related packages to be read in along with the core API. For example, you could load "piechart" and "table" along with the Visualization API.base_domain: The base domain from which to load the API. For example, you
could
load from "ditu.google.cn" with the "maps" module to get the Chinese version of the Maps API.other_params: This is an object that contains options typically only supported by a particular API (and usually very specific to the API). If you would typically send in a parameter by via a script tag for an API, you can send it in other_params instead.See the section below for information on which options are supported for each API.
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.
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:
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.
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);
}
It is possible to auto-load a list of APIs or Javascript libraries when including the loader script. This can be done in order to reduce the load time in many cases by eliminating a single Javascript request at load time. This advanced feature can be difficult to implement, depending on the exact situation. Therefore, we recommend that auto-loading only be considered in specific cases when a reduction in latency is crucial.
To use this feature, you can start with the configuration
wizard. To use it manually, the list of APIs to load is specified in the initial
<script> tag, rather than a separate google.load
call for each. For instance, to auto-load version 1.0 of the Search API (English
language), version 2.X of the Maps API, and the local search element, it would
look like:
{
"modules" : [
{
"name" : "search",
"version" : "1.0",
"language" : "en"
},
{
"name" : "maps",
"version" : "2.X"
},
{
"name" : "elements",
"version" : "1.0",
"packages" : [
"localsearch"
]
}
]
}
This would be compressed to:
{"modules":[{"name":"search","version":"1.0","language":"en"},{"name":"maps","version":"2.X"},{"name":"elements","version":"1.0","packages":["localsearch"]}]}
And then URL encoded to:
%7B%22modules%22%3A%5B%7B%22name%22%3A%22search%22%2C%22version%22%3A%221.0%22%2C%22language%22%3A%22en%22%7D%2C%7B%22name%22%3A%22maps%22%2C%22version%22%3A%222.X%22%7D%2C%7B%22name%22%3A%22elements%22%2C%22version%22%3A%221.0%22%2C%22packages%22%3A%5B%22localsearch%22%5D%7D%5D%7D
This whole string is then appended as the value of the autoload
parameter in the initial <script> tag:
<script src="http://www.google.com/jsapi?autoload=%7B%22modules%22%3A%5B%7B%22name%22%3A%22search%22%2C%22version%22%3A%221.0%22%2C%22language%22%3A%22en%22%7D%2C%7B%22name%22%3A%22maps%22%2C%22version%22%3A%222.X%22%7D%2C%7B%22name%22%3A%22elements%22%2C%22version%22%3A%221.0%22%2C%22packages%22%3A%5B%22localsearch%22%5D%7D%5D%7D&key=ABCDEFG"></script>
Auto-loading supports all of the options that can be passed in using
google.load(module, version, options). See
above for the available options and
below for information on which options are supported
by each API. Note: The callback option is supported, but the value must supply
the name of a function, rather than a function reference.
To automatically generate the necessary code or see an example to get you started, see our configuration wizard.
When an application makes use of the AJAX API loader, the loader attempts to
geo locate the client based on it's IP address. If this process
succeeds, the client's location, scoped to the metro level, is made available
in the google.loader.ClientLocation property. If the process fails
to find a match, this property is set to null.
When populated, the google.loader.ClientLocation object is
populated with the following metro-level granularity properties:
ClientLocation.latitude — supplies the low resolution latitude associated with the client's IP addressClientLocation.longitude — supplies the low resolution longitude associated with the client's IP addressClientLocation.address.city — supplies the name of the city associated with the client's IP addressClientLocation.address.country — supplies the name of the country associated with the client's IP addressClientLocation.address.country_code — supplies the name of the ISO 3166-1 country code associated with the client's IP addressClientLocation.address.region — supplies the country specific region name associated with the client's IP address
Applications must be somewhat defensive when using this property. The google.loader.ClientLocation
is populated by matching an IP address to a location. This mapping is not always possible, so there are times
when the property is null. Additionally, when applications use the address properties as indices
into their data structures, they should range check the results correctly.
The code fragment below demonstrates one possible use case of the API.
/**
* Set the currentState_ and currentCountry_ properties based on the client's
* current location (when available and in the US), or to the defaults.
*/
InTheNews.prototype.setDefaultLocation_ = function() {
this.currentState_ = this.options_.startingState;
if (google.loader.ClientLocation &&
google.loader.ClientLocation.address.country_code == "US" &&
google.loader.ClientLocation.address.region) {
// geo locate was successful and user is in the United States. range
// check the region so that we can safely use it when selecting a
// state level polygon overlay
var state = google.loader.ClientLocation.address.region.toUpperCase();
if (InTheNews.stateNames[state]) {
this.currentState_ = state;
}
}
this.currentCountry_ = "US";
}
The following Google AJAX APIs are available:
google.load("maps", "2");callback, base_domain, language, other_paramsgoogle.load("search", "1");callback, language, nocssgoogle.load("feeds", "1");callback, language, nocssgoogle.load("language", "1");callback, language, nocssgoogle.load("gdata", "1");packagesgoogle.load("earth", "1");google.load("visualization", "1");packagesgoogle.load("friendconnect", "1");google.load("orkut", "1");packages