Google Map API Concepts

Welcome to the developer documentation for the Google Maps API! The Google Maps JavaScript API lets you embed Google Maps in your web pages. To use the API, you need to first sign up for an API key. Once you've received an API key, you can develop a map application following the instructions in this documentation.

Table of Contents

Audience

This documentation is designed for people familiar with JavaScript programming and object-oriented programming concepts. You should also be familiar with Google Maps from a user's point of view. There are many JavaScript tutorials available on the Web.

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 recently reorganized the documentation to add more conceptual information and break out discussions into the following key areas:

• Basic Map Objects
• Map Events
• Map Controls
• Map Overlays
• Map Services

We hope you find the redesign easier to follow, especially for developers who are new to the Maps API. Feedback on the documentation is welcome as well. Make sure to join the Maps API developer forum to give feedback and discuss the API.

Creating Google Mapplets

The Google Maps API now adds supports for Mapplets (Maps + Gadgets), which allow you to embed externally hosted applications within Google Maps. These mapplets are run within their own iFrames, allowing you to create "mashups of mashups" and mix code from one site with another for example. This opens up a whole new world of coding within Google Maps! Writing Mapplets is easy, though some things are done differently than in the standard Google Maps API. Check out the Google Maps Mapplets documentation and reference for more information.

Using the Google AJAX API Loader

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:

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

• Load the specific API you want using the google.load method. The google.load method takes an argument for the specific API and version number to load:

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

• Use the google.maps.* namespace for all classes, methods and properties you currently use in the Google Maps API, replacing the G prefix with this namespace. Perform any initialization to your objects using google.setOnLoadCallback(). For example, the GMap2 object is mapped to google.maps.Map2 when using the Google AJAX API loader:

  <script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
  <script type="text/javascript">
    google.load("maps", "2.x");
     
    // 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);
    }
    google.setOnLoadCallback(initialize);
  </script>
  

Full documentation for using the Google AJAX API loader is available at http://code.google.com/apis/ajax/documentation/.

Localization of the Google Maps API

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 hl parameter to the <script> tag when including the Maps API javascript code, specifying the domain language to use.

For example, to display a Maps API application in German, add &hl=de to the <script> tag as shown below:

<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=abcdefg&hl=de"

See also the supported list of domain languages. Note that we often update supported languages so this list may not be exhaustive.

Programming Notes

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.

Browser Compatibility

The Google Maps API supports the same browsers as the Google Maps website. The script http://maps.google.com/maps?file=api&v=2 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.

XHTML and VML

We recommend that you use standards-compliant XHTML on pages that contain maps. When browsers see the XHTML 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.

If 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">

API Updates

The v parameter within the http://maps.google.com/maps?file=api&v=2 URL refers to the version number of the Google Maps API to use. Most users of the API will want to use the current "Version 2" API by passing the v=2 parameter within that URL. You may instead obtain the latest release (including the latest features) by passing v=2.x instead. However, be aware that the latest release may not be as reliable as the v=2 release. We update the Google Maps API often (sometimes every week), at which point features within the v=2.x release are migrated into the v=2 release unless problems are discovered.

In addition, you may use a "stable" version of the API by passing the v=2.s parameter. This version is updated less often, about every few months. Since the v=2 and v=2.x releases are updated about every two weeks, some developers will prefer to use the stable v=2.s. Please note that the stable version may be several versions behind the current version and therefore may not include some of the latest features.

Each version of the API is labeled as we update it (for example, "Version 2.76"). As we update the API, older code based on previous versions may occasionally not work as advertised. If you absolutely need to peg your application to a particular release of the API, you can do so by explicitly including that version within the v parameter (e.g. v=2.75). However, this is not recommended. It is always best to base your products on the code as it gets updated.

When we do a significant update to the API in the future, we will change up the major version number and post a notice on Google Code and the Maps API developer forum. When that happens we expect to support both versions for at least a month in order to allow you to migrate your code.

The Maps team also transparently updates the API with the most recent bug fixes and performance enhancements. These bug fixes should only improve performance and fix bugs, but we may inadvertently break some API clients. Please use the Maps API developer forum to report such issues.

Upgrading Your v1 Application

This documentation refers to Version 2 of the Maps API, launched on April 3, 2006. If your API uses Version 1 of the Maps API (i.e., you developed your site before April 3, 2006), you should attempt to upgrade your web site. Please see the Version 2 Upgrade Guide for more information.

Examples in the Maps API

Note that most of the examples in this documentation show only relevant JavaScript code, not the full HTML file. You can plug the JavaScript code into your own skeleton HTML file, or you can download the full HTML file for each example by clicking the link after the example.

Reducing Browser Memory Leaks

The Google Maps API encourages the use of function closures, and the API event handling system GEvent 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:

<body onunload="GUnload()">

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.

Other resources

Here are some additional resources. Note that these sites are not owned or supported by Google.

• Google Mapki: Mapki
• Google Maps API Tutorial: http://econym.googlepages.com/index.htm
• Esa's Google Maps API Examples: http://koti.mbnet.fi/ojalesa/exam/index.html
• USNaviguide's Maps API Examples: http://maps.huge.info/examples.htm
• Mark McClure's Encoded Polyline Examples: http://facstaff.unca.edu/mcmcclur/GoogleMaps/EncodePolyline/
• Marcelo's Maps API Experiments: http://maps.forum.nu/
• Bill Chadwick's Maps API Demos: http://www.bdcc.co.uk/Gmaps/BdccGmapBits.htm

Troubleshooting

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.
• Look for typos. Remember that JavaScript is a case-sensitive language.
• Use a JavaScript debugger. In Firefox, you can use the JavaScript console, the Venkman Debugger, or the Firebug add-on. In IE, you can use the Microsoft Script Debugger. This series of screencasts demonstrates how to use the various debugging tools.
• 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.
• See Other Resources for third party developer resources.