Table of Contents
This conceptual documentation is not complete and exhaustive; it is designed to let you quickly start exploring and developing cool applications with the Google Maps API. We also publish the Google Maps API Reference which should be relatively complete.
We've reorganized the documentation to add more conceptual information and break out discussions into the following key areas:
The Google Maps API is now fully integrated with the Google AJAX APIs. This framework allows you to load one API key for all supported Google AJAX APIs (including Google Maps) and also provides a common namespace for each API, allowing different Google APIs to operate together. Don't worry: if you decide not to use the Google AJAX API framework, you can continue to use the existing namespace.
Using the Google AJAX API framework is relatively simple. Changing your application to use the framework involves the following steps:
- Instead of loading the API from
http://maps.google.com/apis, you load the common loader from
http://www.google.com/jsapi. You can pass your existing Google Maps API key to this URL:
- Load the specific API you want using the
google.loadmethod takes an argument for the specific API and version number to load:
- Use the
google.maps.*namespace for all classes, methods and properties you currently use in the Google Maps API, replacing the
Gprefix with this namespace. Perform any initialization to your objects using
google.setOnLoadCallback(). For example, the
GMap2object is mapped to
google.maps.Map2when using the Google AJAX API loader:
Full documentation for using the Google AJAX API loader is available at http://code.google.com/apis/ajax/documentation/.
The Google Maps API uses the browser's preferred language setting when displaying textual
information such as the names for controls, copyright notices, and driving directions. If you
wish to change the Maps API to ignore the browser's language setting and force it to
display information in a particular language, you can add an optional
parameter to the
code, specifying the domain language to use.
For example, to display a Maps API application in German, add
<script> tag as shown below:
See also the supported list of domain languages. Note that we often update supported languages so this list may not be exhaustive.
Bidirectional languages, such as Arabic and Hebrew, require special consideration.
These languages affect the layout of info windows and other UI elements in the
Maps API. As a result, the Maps API will only implement these languages if explicitly
set through an applicable
hl parameter, or if the Maps API is loaded with an
allow_bidi=true parameter and the user's browser setting specifies a
bidirectional language. Note that browser settings are insufficient to enforce
a language change on their own.
The Google Maps API provides a read-only
GLanguage namespace useful to
query the language settings in use by a Maps API application. In specific,
GLanguage.getLanguageCode() returns the BCP 47 language code in use by the
GLanguage.isRtl() queries whether the language is
GLanguage reference documentation for more information.)
Use of the Google Maps API now requires that you indicate whether your application is using a
sensor (such as a GPS locator) to determine the user's location. This is especially important for
mobile devices. Applications must pass a required
sensor parameter to the
your application is using a sensor device.
Applications that determine the user's location via a sensor must pass
or with the Common Loader.
Note that even if your device does not use a sensing device, you must still pass this parameter, setting
its value to
Before you start delving into the Google Maps API, you should take note of the following concerns to ensure your application works smoothly across its intended platforms.
The Google Maps API supports the
as the Google Maps website. The script
can be parsed in almost every browser without errors, so you can safely include that script before
checking for compatibility.
Different applications sometimes require different behaviors for users with incompatible browsers.
The Maps API provides a global method (
GBrowserIsCompatible()) to check compatibility,
but it does not have any automatic behavior when it detects an incompatible browser. Most of the
examples in this document do not check for browser compatibility, nor do they
display an error message for older browsers. Clearly real applications should do something
more friendly with incompatible browsers, but we have omitted such checks to make the
examples more readable.
Non-trivial applications will inevitably encounter inconsistencies between browsers and platforms. There is no simple solution to these problems, but the Google Maps API developer forum and quirksmode.org are both good resources to find workarounds.
The Google Maps API, by default, outputs and provides text elements using UTF-8 character encoding. In most cases, this is preferable. However, you may encounter problems if your HTML page is encoded using a different encoding scheme. In those cases, you will want to ensure that your HTML page and the Google Maps API are set up to use the same encoding scheme.
You can set your HTML page's encoding scheme by setting the
parameter within the
<meta charset="utf-8" />
If your web application supports UTF-8, set your
<meta> tag as shown above.
All of the examples within the Maps API documentation use this encoding scheme.
There may be cases in which you may use (or must use) a different character encoding
in your web page. In those cases, you can set the output encoding for the Maps API using the
oe parameter when you first load the Maps API with the
oe parameter supports many encoding values, including the most popular
utf8UTF-8 encoding (default)
latin1ISO-8859-1 Western European
latin2ISO-8859-2 Eastern European
Note that default encoding of
oe=utf-8 is highly preferred. Only set a different encoding
if you have an HTML page that does not support UTF-8.
For more information on encoding schemes, see Character Encoding.
We recommend that you use standards-compliant HTML5 on pages that contain maps. When browsers see the HTML
DOCTYPE at the top of the page, they render the page in "standards compliance mode," which makes
layout and behaviors much more predictable across browsers. Pages without that definition may render in
"quirks mode" which can lead to inconsistent layout. We
recommend that the beginning of your HTML document should look like this:
<!DOCTYPE html> <html>
If you are using XHTML on your page and you want to show polylines on your map (like the lines used by Google Maps to show driving directions), you need to include the VML namespace in your XHTML document to make everything work properly in Internet Explorer. The beginning of your XHTML document should look like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
You can indicate which version of the API that you'd like to use within
your application by specifying the
v parameter of the Maps
- The stable version, specified with
- The current released version, specified with
v=2. This is the version that most customers will choose to use.
- The experimental version, specified with
If the API does not recognize the version specified, it will default to
This example demonstrates how to load the current released version of the API.
- When an update is required, the changes will be made to the
v=2.xversion and a notification will be posted to the google-maps-api-notify group.
- After two weeks, the changes made to version
v=2.xwill be copied to
- Four weeks after the change to
v=2, the changes will be made to version
All changes to the API will be backwards-compatible. If you encounter any problems with your application following bug fixes, please use the Maps API developer forum to report these issues.
The Google Maps API encourages the use of
function closures, and the API event handling system
attaches events to DOM nodes in such a way that almost inevitably
causes some browsers to leak memory,
particularly Internet Explorer. Version 2 of the Maps API
introduces a new method,
GUnload(), that will remove
most of the circular references that cause these leaks. You should call
GUnload() in the
onunload event of your page
to reduce the potential that your application leaks memory:
Using this function has virtually eliminated Internet Explorer memory leaks in Google Maps, though you should test for memory leaks on your own site using tools like Drip if you are noticing memory consumption problems.
If your code doesn't seem to be working, here are some approaches that might help you solve your problems:
- Make sure your API key is valid.
- Search the Maps API developer forum. If you can't find a post that answers your question, post your question to the group along with a link to a web page that demonstrates the problem.