Using Google's AJAX APIs——Google 地图 API 文档之二
Table of Contents
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 locale of the Maps API user interface with:
google.load("maps", "2", {"locale" : "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, locale 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.
Available AJAX APIs
The following Google AJAX APIs are available: