Google Maps API Version 2 Upgrade Guide

This documentation describes how to upgrade from Version 1 of the Google Maps API to Version 2, launched on April 3, 2006. If you developed your site before April 3, 2006, you should follow the instructions in this document to update your site to use the most recent version of the API.

Table of Contents

Introduction

Upgrade Overview

Version 2 of the Maps API is designed to be 99% backwards-compatible with the previous version of the API. Version 2 introduces a new map class, GMap2, that contains an updated interface with new method names. The old map class, GMap, will continue to exist in Version 2 of the API and contains the same ocumented interface as Version 1 of the API. However, most of the new features introduced in Version 2 of the API only work with the new GMap2 Map interface.

Given this design, you have two upgrade paths:

• Continue using the same GMap interface without new Version 2 features.
  The quickest way to upgrade is to update your Maps API <script> URL to refer to "v=2" instead of "v=1." Since Version 2 preserves the old GMap interface, your site should theroretically continue to work without any further changes. However, in practice, you may have to spend some time debugging. Please see the Incompatibilities section for a list of known incompatibilities between Version 1 and Version 2 of the API, and join the Maps API discussion group if you continue having problems.
• Upgrade to the GMap2 interface to take advantage of Version 2 features.
  To take advantage of Version 2 features like tabbed info windows and custom map controls, start using GMap2 instead of GMap. First, update your Maps API <script> URL to refer to "v=2" instead of "v=1." Then, update your code based on our detailed GMap2 upgrade guide below.

We did not preserve many of the undocumented functions between Version 1 and 2 of the API. We expect that this will be the biggest source of frustration for sites upgrading to this new version of the API.

Who Needs to Upgrade?

Every Maps API site should upgrade. Version 2 contains many important enhancements to fundamental parts of the Maps API, and Version 1 will be turned off once most sites have successfully upgraded.

Version 1 and Version 2 will coexist for at least one month no matter how few bugs are reported, and we may preserve Version 1 of the API for longer if people report many or complex transition problems. At that time, Version 2 will become the "default," and all sites will automatically start using it. Please report your problems to the Google Maps API discussion group, which our support staff actively moderates.

Incompatibilities Between Version 1 and Version 2

There are small number of incompatibilities between the documented features of Version 1 and Version 2, including:

• GXslt browser support
  GXslt now only supports browsers with native XSLT support. Safari does not have native XSLT support, so GXslt no longer supports Safari. You can include Google's open source AJAXSLT library to reproduce this behavior in Safari if it is important for your application.
• openInfoWindowXslt() methods
  GMap and GMarker no longer support the openInfoWindowXslt() method due to the changes to GXslt.
• Map initialization order (setMapType)
  Version 1.0 let you call setMapType before centerAndZoom. Version 2.0 does not allow setMapType to be called before the map location is initialized. If you are upgrading to GMap2, we recommend you use the new setCenter method in GMap2 to initialize the center, zoom level, and map type in a single method call.
• Undocumented methods
  Version 2 of the Maps API contains significant changes to the core parts of the API, so almost all of the undocumented functions have changed or are no longer supported.

Upgrading from GMap to GMap2

The GLatLng Class

Geographical coordinates and pixel coordinates are now expressed as separate classes, GLatLng and GPoint. Methods like setCenter now take in instances of GLatLng instead of instances of GPoint, so many of your method calls will have to be updated to reflect this when you upgrade to GMap2.

Version 2 also introduces the GLatLngBounds class, which properly respects the international date line.

See the class reference for more information.

Zoom Level Order

Zoom level indices in GMap2 start with 0 at the coarsest level, not at the finest. This allows maps of arbitrarily high resolution, which will let us more easily introduce high resolution imagery. You can convert between old and new zoom levels with the following formula:

newZoom = 17 - oldZoom

Map Type Name Changes

The Map types (Map, Satellite, Hybrid) have new names in Version 2 of the API:

• G_NORMAL_MAP
• G_SATELLITE_MAP
• G_HYBRID_MAP

Method Name Changes

Many of the methods in the GMap interface have been replaced with new methods that use the GLatLng class and are more consistent with our new, extensible GMap2 interface. You can update your constructor calls, method invocations, and event handler based on the table below:

New Features in Version 2

Version 2 of the Maps API introduces a number of new features, including:

• Much smaller JavaScript download
  The new Maps API JavaScript file is about half the size of the old JavaScript file, which should improve user experience on your web site.
• Two additional satellite zoom levels
  Increased imagery resolution and coverage in the U.S., Canada, U.K., Japan, Europe, and almost every major city in the world.
• Overview map control
  Our new GOverviewMapControl control displays an attractive and collapsible map in the corner of the screen.
• Custom map controls
  You can define subclasses of GControl to define custom map controls in addition to the built-in controls like GSmallMapControl. See the example or class reference for more information.
• Custom map overlays
  You can define subclasses of GOverlay to define custom map overlays in addition to the built-in GMarker and GPolyline classes. See the example or class reference for more information.
• Fewer memory leaks
  The API now includes a GUnload() method that you can call in the unload event of your page to destroy most circular references, including those formed implicitly during event registration. On Google Maps, this has virtually eliminated memory leaks in IE. See the documentation for more information.
• Debugging log
  A simple, floating debug window used internally by the Google Maps engineering team allows you to print debug information easily without blocking program execution or interfering with the UI. Just replace your alert() calls with GLog.write(). See the class reference for more information.