Google Maps JavaScript API v2 (Deprecated)

Google Maps API Concepts

Version 2 of the JavaScript API has been turned down

Warning: Version 2 of the Google Maps JavaScript API is no longer available. Please follow the guide to migrate your code to version 3 of the Google Maps JavaScript API. As of November 19, 2013, all applications requesting v2 are served a special, wrapped version of the v3 API instead. We expect this wrapped version of the API to work for most simple maps, but we strongly encourage you to migrate to the v3 API immediately.

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

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="https://www.google.com/jsapi?key=API_KEY"></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=API_KEY"></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=API_KEY&hl=de"

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.

<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=API_KEY&allow_bidi=true"

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 application, while GLanguage.isRtl() queries whether the language is bi-directional.

(See the GLanguage reference documentation for more information.)

Specifying the Sensor Parameter

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 <script> tag when including the Maps API javascript code, indicating whether or not your application is using a sensor device.

Applications that determine the user's location via a sensor must pass&sensor=true when loading the Maps API JavaScript via either the http://maps.google.com/maps or with the Common Loader.

#
# Example using sensor when loading the Maps JavaScript API
#
<script type="text/javascript" src="http://maps.google.com/maps?file=api&v=2&key=API_KEY&sensor=true">
#
# Example using sensor when loading the Maps API via the common loader
#
<script type="text/javascript" src="http://www.google.com/jsapi?key=API_KEY"></script>
<script type="text/javascript">
  google.load("maps", "2",{"other_params":"sensor=true"});

  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>

Note that even if your device does not use a sensing device, you must still pass this parameter, setting its value to false.

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.

Character Encoding

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 charset parameter within the <meta> tag:

<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 <script> tag. The oe parameter supports many encoding values, including the most popular noted below:

  • utf-8 or utf8 UTF-8 encoding (default)
  • iso-8859-1 or latin1 ISO-8859-1 Western European
  • iso-8859-2 or latin2 ISO-8859-2 Eastern European
  • iso-8859-5 or cyrillic Russian (Cyrillic)
  • iso-8859-7 or greek Greek
  • iso-8859-8 or hebrew Hebrew
  • shift_jis Japanese
  • gb2312 Simplified Chinese
  • big5 Traditional Chinese

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.

HTML, XHTML and VML

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

API Updates

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 JavaScript API bootstrap request. Three options are supported:

  • The stable version, specified with v=2.s.
  • The current released version, specified with v=2. This is the version that most customers will choose to use.
  • The experimental version, specified with v=2.x. This version reflects the current version based off the trunk, including the latest bug fixes. As the Google Maps JavaScript API v2 is deprecated, we recommend that you only use this version for testing bug fixes after they have been announced on the google-maps-api-notify group.

If the API does not recognize the version specified, it will default to v=2.

This example demonstrates how to load the current released version of the API.

<script src="http//maps.google.com?file=api&v=2&key=API_KEY" type="text/javascript"></script>

Release Cycle

The Google Maps JavaScript API v2 is deprecated, and is not subject to regular releases. Occasionally, we will need to update the current release with bug fixes or other necessary changes. When updates are required, the release cycle will be as follows:

  1. When an update is required, the changes will be made to the v=2.x version and a notification will be posted to the google-maps-api-notify group.
  2. After two weeks, the changes made to version v=2.x will be copied to v=2.
  3. Four weeks after the change to v=2, the changes will be made to version v=2.s.

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.

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.

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.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.