Upgrading Your Maps JavaScript API Application from V2 to V3

New Event for MVC Support

The v3 API adds a new type of event to reflect MVC state changes. There are now two types of events:

• User events (such as "click" mouse events) are propagated from the DOM to the Maps JavaScript API. These events are separate and distinct from standard DOM events.
• MVC state change notifications reflect changes in Maps API objects and are named using a property_changed convention.

Each Maps API object exports a number of named events. Applications interested in specific events should register event listeners for those events and execute code when those events are received. This event-driven mechanism is the same in both the Maps JavaScript API v2 and v3, except that the namespace has changed from GEvent to google.maps.event:

GEvent.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

google.maps.event.addListener(map, 'click', function() {
  alert('You clicked the map.');
});

Removing Event Listeners

For performance reasons, it's best to remove an event listener when it is no longer needed. Removing an event listener works the same way in v2 and v3:

1. When you create an event listener, an opaque object (GEventListener in v2, MapsEventListener in v3) is returned.
2. When you want to remove the event listener, pass this object to the removeListener() method (GEvent.removeListener() in v2 or google.maps.event.removeListener() in v3) to remove the event listener.

Listening to DOM Events

If you wish to capture and respond to DOM (Document Object Model) events, v3 provides the google.maps.event.addDomListener() static method, equivalent to the GEvent.addDomListener() method in v2.

Using Passed Arguments in Events

UI events often pass an event argument which can then be accessed by the event listener. Most event arguments in v3 have been simplified to be more consistent over objects in the API. (Consult the v3 Reference for details.)

No overlay argument exists in v3 event listeners. If you register a click event on a v3 map the callback will only occur when the user clicks on the base map. You can register additional callbacks on clickable overlays if you need to react to those clicks.

// Passes an overlay argument when clicking on a map

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

GEvent.addListener(map,'click', function(overlay, latlng) {
  if (latlng) {
    var marker = new GMarker(latlng);
    map.addOverlay(marker);
  }
});

// Passes only an event argument

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

google.maps.event.addListener(map, 'click', function(event) {
  var marker = new google.maps.Marker({
      position: event.latLng,
      map: map
  });
});

Changes in Control Types

Some changes to control types have been introduced with the v3 API.

1. The v3 API supports additional map types including terrain maps and the ability to add custom map types.
2. The v2 hierarchical control, GHierarchicalMapTypeControl, is no longer available. You can achieve a similar effect by using the google.maps.MapTypeControlStyle.HORIZONTAL_BAR control.
3. The horizontal layout provided by GMapTypeControl in v2 is not available in v3.

Adding Controls to the Map

With the Maps JavaScript API v2 you would add controls to your map through the addControl() method of your map object. In v3, instead of accessing or modifying controls directly, you modify the associated MapOptions object. The below sample shows how to customize the map to add the following controls:

• buttons that let the user toggle between available map types
• a map scale

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add controls
map.addControl(new GMapTypeControl());
map.addControl(new GScaleControl());

var myOptions = {
    center: new google.maps.LatLng(-25.363882, 131.044922),
    zoom: 4,
    mapTypeId: google.maps.MapTypeId.ROADMAP,

    // Add controls
    mapTypeControl: true,
    scaleControl: true
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

Positioning Controls on the Map

Positioning controls has changed a great deal in v3. In v2, the addControl() method takes an optional second parameter that lets you specify the position of the control relative to the corners of the map.

In v3, you set the position of a control through the position property of the control options. Positioning of these controls is not absolute; instead, the API will layout the controls intelligently by "flowing" them around existing map elements within given constraints (such as the map size). This ensures that default controls are compatible with your controls. See Control Positioning in v3 for more information.

The following code re-positions controls from the above samples:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);

// Add map type control
map.addControl(new GMapTypeControl(), new GControlPosition(
    G_ANCHOR_TOP_LEFT, new GSize(10, 10)));

// Add scale
map.addControl(new GScaleControl(), new GControlPosition(
    G_ANCHOR_BOTTOM_RIGHT, new GSize(20, 20)));

var myOptions = {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP,

  // Add map type control
  mapTypeControl: true,
  mapTypeControlOptions: {
      style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
      position: google.maps.ControlPosition.TOP_LEFT
  },

  // Add scale
  scaleControl: true,
  scaleControlOptions: {
      position: google.maps.ControlPosition.BOTTOM_RIGHT
  }
};

var map = new google.maps.Map(document.getElementById('map'),
    myOptions);

Custom Controls

The Maps JavaScript API allows you to create custom navigational controls. To customize controls with the v2 API, you would subclass the GControl class and define handlers for the initialize() and getDefaultPosition() methods. There is no equivalent to the GControl class in v3. Instead, controls are represented as DOM elements. To add a custom control with the v3 API, create a DOM structure for the control in a constructor as a child of a Node (e.g. a <div> element) and add event listeners to handle any DOM events. Push the Node into the maps' controls[position] array to add an instance of the custom control to your map.

Given a HomeControl class implementation that adheres to the interface requirements noted above (see Custom Controls documentation for details), the following code samples show how to add a custom control to a map.

map.addControl(new HomeControl(),
    GControlPosition(G_ANCHOR_TOP_RIGHT, new GSize(10, 10)));

var homeControlDiv = document.createElement('DIV');
var homeControl = new HomeControl(homeControlDiv, map);

map.controls[google.maps.ControlPosition.TOP_RIGHT].push(
    homeControlDiv);

Adding and Removing Overlays

The types of objects represented by an Overlay are the same between v2 and v3, however, they are handled differently.

Overlays in the v2 API were added to and removed from the map using the addOverlay() and removeOverlay() methods of the GMap2 object. In v3, you assign a map to an Overlay via the map property of the associated overlay options class. You may also add or remove an overlay directly by calling the setMap() method of the overlay object, and specifying the desired map. Setting the map property to null removes the overlay.

No clearOverlays() method exists in v3. If you wish to manage a set of overlays, you should create an array to hold the overlays. Using this array, you can then call setMap() on each overlay in the array (passing null if you need to remove them).

Draggable Markers

By default, markers are clickable but not draggable. The following two samples add a draggable marker:

var myLatLng = new GLatLng(-25.363882, 131.044922);
var map = new GMap2(document.getElementById('map'));
map.setCenter(myLatLng, 4);

var marker = new GMarker(latLng, {
  draggable: true
});
map.addOverlay(marker);

var myLatLng = new google.maps.LatLng(-25.363882, 131.044922);
var map = new google.maps.Map(
  document.getElementById('map'), {
  center: myLatLng,
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var marker = new google.maps.Marker({
    position: myLatLng,
    draggable: true,
    map: map
});

Icons

You can define a custom icon to show in place of the default marker. To use a custom image in v2, you can create a GIcon instance from the G_DEFAULT_ICON type, and modify it. If your image is larger or smaller than the default icon, you must specify it with a GSize instance. The v3 API simplifies this process slightly. Simply set the marker's icon property to the URL of your custom image, and the API will size the icon automatically.

The Maps JavaScript API also provides support for complex icons. A complex icon may include multiple tiles, complex shapes, or specify the "stack order" of how the images should display relative to other overlays. To add a shape to a marker in v2, you need to specify the additional property in each GIcon instance and pass this as an option to a GMarker constructor. In v3, icons specified in this manner should set their icon properties to an object of type Icon. Marker shadows are not supported in v3.

The following examples display a beach flag at Bondi Beach in Australia, with the transparent part of the icon not clickable:

var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();

var flagIcon = new GIcon(G_DEFAULT_ICON);
flagIcon.image = '/images/beachflag.png';
flagIcon.imageMap = [1, 1, 1, 20, 18, 20, 18 , 1];
var bbLatLng = new GLatLng(-33.890542, 151.274856);

map.addOverlay(new GMarker(bbLatLng, {
  icon: flagIcon
}));

var map = new google.maps.Map(
  document.getElementById('map'), {
  center: new google.maps.LatLng(-25.363882, 131.044922),
  zoom: 4,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

var shape = {
    coord: [1, 1, 1, 20, 18, 20, 18 , 1],
    type: 'poly'
};
var bbLatLng = new google.maps.LatLng(-33.890542, 151.274856);

var bbMarker = new google.maps.Marker({
    icon: '/images/beachflag.png'
    shape: shape,
    position: bbLatLng,
    map: map
});

Polylines

A polyline consists of an array of LatLngs, plus a series of line segments that connect those locations in an ordered sequence. Creating and displaying a Polyline object in v3 is similar to using a GPolyline object in v2. The following samples draw a semi-transparent, 3-pixel wide, geodesic polyline from Zurich to Sydney through Singapore:

var polyline = new GPolyline(
  [
    new GLatLng(47.3690239, 8.5380326),
    new GLatLng(1.352083, 103.819836),
    new GLatLng(-33.867139, 151.207114)
  ],
  '#FF0000', 3, 0.5, {
  geodesic: true
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: [
    new google.maps.LatLng(47.3690239, 8.5380326),
    new google.maps.LatLng(1.352083, 103.819836),
    new google.maps.LatLng(-33.867139, 151.207114)
  ],
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
  geodesic: true
});

polyline.setMap(map);

Encoded Polylines

No support exists in v3 for creating Polyline objects directly from encoded polylines. Instead, the The Geometry Library provides methods to encode and decode polylines. See Libraries in the v3 Maps API for more information on how to load this library.

The examples below draw the same encoded polyline; the v3 code uses the decodePath() method from the google.maps.geometry.encoding namespace.

var polyline = new GPolyline.fromEncoded({
  points: 'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H',
  levels: 'PPP',
  zoomFactor: 2,
  numLevels: 18,
  color: '#ff0000',
  opacity: 0.8,
  weight: 3
});

map.addOverlay(polyline);

var polyline = new google.maps.Polyline({
  path: google.maps.geometry.encoding.decodePath(
    'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H'),
  strokeColor: '#FF0000',
  strokeOpacity: 0.5,
  strokeWeight: 3,
});

polyline.setMap(map);

Polygons

A Polygon defines a region within a closed loop. Much like the Polyline object, Polygon objects consist of a series of points in an ordered sequence. The v3 Polygon class is much the same as the v2 GPolygon class, with the notable exception that you no longer have to repeat the starting vertex at the end of the path to close the loop. The v3 API will automatically close any polygons by drawing a stroke connecting the last coordinate back to the first coordinate. The following code snippets create a polygon representing the Bermuda Triangle:

var map = new GMap2(document.getElementById('map'));

map.setCenter(new GLatLng(24.886436, -70.268554), 5);

var bermudaTriangle = new GPolygon(
  [
    new GLatLng(25.774252, -80.190262),
    new GLatLng(18.466465, -66.118292),
    new GLatLng(32.321384, -64.75737),
    new GLatLng(25.774252, -80.190262)
  ],
  '#FF0000', 2, 0.8, '#FF0000', 0.35);

map.addOverlay(bermudaTriangle);

var map = new google.maps.Map(document.getElementById('map'), {
  center: new google.maps.LatLng(24.886436, -70.268554),
  mapTypeId: google.maps.MapTypeId.TERRAIN,
  zoom: 5
});

var bermudaTriangle = new google.maps.Polygon({
  paths: [
    new google.maps.LatLng(25.774252, -80.190262),
    new google.maps.LatLng(18.466465, -66.118292),
    new google.maps.LatLng(32.321384, -64.75737)
  ],
  strokeColor: '#FF0000',
  strokeWeight: 2,
  strokeOpacity: 0.8,
  fillColor: '#FF0000',
  fillOpacity: 0.35
});

bermudaTriangle.setMap(map);

User-Editable Shapes

Polylines and polygons can be made user-editable. The following code snippets are equivalent:

map.addOverlay(polyline);
polyline.enableEditing();

polyline.setMap(map);
polyline.setEditable(true);

For more advanced drawing capabilities, see the Drawing Library in the v3 documentation.

Info Windows

An InfoWindow displays content in a floating window above the map. There are a few key differences between v2 and v3 info windows:

• The v2 API supports only GInfoWindow per map, whereas the v3 API supports multiple, concurrent InfoWindows on each map.
• The v3 InfoWindow will remain open when you click on the map. The v2 GInfoWindow closes automatically when you click on the map. You can emulate the v2 behavior by adding a click listener on the Map object.
• The v3 API does not provide native support for a tabbed InfoWindow.

Ground Overlays

To place an image on a map, you should use a GroundOverlay object. The constructor for a GroundOverlay is essentially the same in v2 and v3: it specifies a URL of an image and the boundaries of the image as parameters.

The following example places an antique map of Newark, NJ on the map as an overlay:

var bounds = new GLatLngBounds(
    new GLatLng(40.716216, -74.213393),
    new GLatLng(40.765641, -74.139235));

var overlay = new GGroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

map.addOverlay(overlay);

var bounds = new google.maps.LatLngBounds(
    new google.maps.LatLng(40.716216, -74.213393),
    new google.maps.LatLng(40.765641, -74.139235));

var overlay = new google.maps.GroundOverlay(
    'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
    bounds);

overlay.setMap(map);

Common Map Types

The four basic map types are available in both v2 and v3:

• MapTypeId.ROADMAP (replaces G_NORMAL_MAP) displays the road map view.
• MapTypeId.SATELLITE (replaces G_SATELLITE_MAP) display Google Earth satellite images.
• MapTypeId.HYBRID (replaces G_HYBRID_MAP) displays a mixture of normal and satellite views.
• MapTypeId.TERRAIN (replaces G_PHYSICAL_MAP) displays a physical map based on terrain information.

Below is an example of v2 and v3 setting the map to terrain view:

map.setMapType(G_PHYSICAL_MAP);
    

map.setMapTypeId(google.maps.MapTypeId.TERRAIN);
    

The Maps JavaScript API v3 made a few changes to the less common map types as well:

• Map tiles for celestial bodies other than Earth are not available as map types in the v3 API, but can be accessed as custom map types as shown in this example.
• There is no special map type in v3 that replaces the G_SATELLITE_3D_MAP type from v2. Instead, you can integrate the Google Earth plugin in your v3 maps using this library.

Maximum Zoom Imagery

Satellite imagery is not always available at high zoom levels. If you may want to know the highest zoom level available before setting the zoom level, use the google.maps.MaxZoomService class. This class replaces the GMapType.getMaxZoomAtLatLng() method from v2.

var point = new GLatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new GMap2(document.getElementById("map"));
map.setUIToDefault();
map.setCenter(point);
map.setMapType(G_HYBRID_MAP);

map.getCurrentMapType().getMaxZoomAtLatLng(point,
  function(response) {
    if (response.status) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

var myLatlng = new google.maps.LatLng(
    180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new google.maps.Map(
  document.getElementById("map"),{
    zoom: 0,
    center: myLatlng,
    mapTypeId: google.maps.MapTypeId.HYBRID
});
var maxZoomService = new google.maps.MaxZoomService();
maxZoomService.getMaxZoomAtLatLng(
  myLatlng,
  function(response) {
    if (response.status == google.maps.MaxZoomStatus.OK) {
      map.setZoom(response.zoom);
    } else {
      alert("Error in Max Zoom Service.");
    }
});

Aerial Perspective Imagery

When enabling Aerial imagery in v3, controls are similar to the v2 GLargeZoomControl3D control, with an additional interstitial Rotate control to rotate through supported directions.

You can track the cities where 45° imagery is currently available on this map. When 45° imagery is available, a submenu option is added to the Maps API Satellite button.