v2.78: Go ahead, Scroll your mouse wheels & encode your polygons!

Tuesday, April 17, 2007 at 7:25:00 PM



The latest version of the API exposes two features that have often been requested (or reverse engineered) by API developers: the ability to enable the mouse wheel zoom used on maps.google.com, and the ability to create GPolygons from encoded points.

To get started using the new features, read through the examples and explanations below.


1) Scroll wheel zoom:

The API gives you these 2 new GMap2 methods: enableScrollWheelZoom, disableScrollWheelZoom. These functions let you turn scroll wheel zoom on or off.

If you'd just like to modify your current map mashups to enable this user-friendly zoom, add the following line of code anywhere after you've created your map.

map.enableScrollWheelZoom();

You should see results like the example below. For the complete code to this map, view the source on this link.

Note: You'll notice the webpage scrolls along with the map. This is expected behavior, as the scroll wheel zoom is optimized for the screen-filling map on maps.google.com. Many maps site use a similar design, but if you do have a long webpage with an embedded map, you can write some extra javascript to get better behavior (here's one developer's suggestion).

If you'd like to let your users choose whether to enable the mouse wheel zoom, or you'd like to see how to disable it at certain times, check out the toggling example below, and view source on this link to see how it's done.



2) Encoded GPolygons

In 2.63, we introduced GPolyline.fromEncoded(), a factory method that lets you create a polyline based on encoded points and levels. This technique is useful for developers using long and complicated lines, as the encoding algorithm both saves storage space and lets you specify which points are displayed at each zoom level.

When GPolygon was announced in version 2.69, developers immediately asked if a GPolygon.fromEncoded method was also available so they could use the same effficient technique. Well, the engineers heard their call and have exposed GPolygon.fromEncoded() in the API.

This new factory method lets you create a polygon based on a set of encoded polylines, and specify the fill/stroke for the resultant polygon(s). The example below shows Texas and a (fictional) island near it, created using the GPolygon.fromEncoded method with 2 encoded polylines.

The Texas polyline encoding comes from this example from Mark McClure, a Mathematics professor/API hobbyist who's done extensive work with the polyline encoding scheme. Check out his useful page that has more information and examples of polyline encoding, including a utility to automatically encode a set of latitude/longitude points using an extended Douglas-Peucker algorithm.

You can also reference the API documentation's encoded polylines example, and related polyline encoding utility for more help.

Note: Remember that you'll need to specify v=2.x in your script tag to use the new functions for the next few weeks, since they're new features. More information on API script versioning is here.



API v2 Latest (v=2.x): 2.78
API v2 Default (v=2): 2.77