Polylines are used to mark out roads, borders and other things that are made of lines in maps. The Google Maps API offers a class for drawing these lines on a Google Map called GPolyline. In this article I will show you how to use these and how to deal with potential performance issues when the polylines gets more complex.

A basic polyline

Polylines consists of several points forming a line. Like for example a road on a map.

Normally you create a GPolyline and add it to the map using GMap2.addOverlay().

// Create an instance of Google map
var map = new GMap2(document.getElementById("map"));

// Tell the map where to start
map.setCenter(new GLatLng(59.3324, 17.8857), 9);

// Create an array with points
var points = [
   new GLatLng(59.6919, 17.8582),
   new GLatLng(59.3030, 18.0395),
   new GLatLng(58.9789, 17.5341)
];

// Create a new polyline
var polyline = new GPolyline(points, '#ff0000', 5, 0.7);

// Add the polyline to the map using map.addOverlay()
map.addOverlay(polyline);

As you can see GPolyline takes four arguments. The first one is the only required one, and it’s the coordinates for the polyline. The other ones are optional and are settings for how the polyline will appear. They are, from left to right, the color, the thickness and the opacity of the polyline.

Watch the small polyline example.

This works fine as long as the polyline doesn’t consist of too many coordinates. However when the polyline is more complex the rendering becomes really slow.

More complex polylines

Here’s an example of five polylines with a total of 7841 coordinates which are added to the map the same way as the previous example. You’ll notice that the performance is really starting to degrade. The load time is longer and when you zoom in or out on the map you’ll notice a significant delay.

Watch the complex polylines example (Warning: The loading time can be long)

The performance vary from browser to browser. So if you try the example with Internet Explorer it’s really slow, but with Safari or Google Chrome it’s still pretty fast.

Data format

In the example the coordinates are fetched through an AJAX call to a file containing the coordinates in JSON format. The data structure looks like this:

[{
    "Name":"Section 1",
    "Geom":[[59.1949,17.6596],[59.1942,17.6591],[59.1941,17.659]]
},
{
    "Name":"Section 2",
    "Geom":[[59.3819,18.0088],[59.3819,18.0089],[59.3818,18.0091]]
},

I only show three points per Section here but in the used file there a total of five Sections with thousands of points each.

Better performance

Decrease the number of coordinates

One easy way to make it faster is to try to limit the number of coordinates that you serve to the map. You gain some performance but loose accuracy, especially when you zoom in on the page.

Encoded polylines on the fly

A far better solution is to encode the polylines. It provides much better performance than just decreasing the number of coordinates plus you get better accuracy. The algorithm that encodes the coordinates removes some coordinates but more importantly decreases the number of coordinates when you zoom out, and increase them when zooming in.

Here’s how it’s done.

Instead of just feeding the map with coordinates you first encode them. An excellent encoder is Mark McClure’s PolylineEncoder class. It’s available from Encoding polylines for Google Maps. You can also download PolylineEncoder.js from there.

The encoder doesn’t make a very big difference on the loading time of the page, but when you start zooming and panning, the difference is huge.

Encoding the coordinates

Put all your coordinates in an array and feed it to dpEncodeToGPolyline() in the polylineEncoder class. The coordinates should be in the GLatLng format.

As you may notice dpEncodeToGPolyline() takes exactly the same arguments as GPolyline() and returns a GPolyline. So basically you just call dpEncodeToGPolyline() instead of GPolyline() and then add it to the map with addOverlay(), just like you did with the regular polyline.

// Create an array that will hold the coordinates
var points = [];

// Loop through the coordinates.
// In this case the coordinates are in a JSON object
for(var j = 0; j < json[i].Geom.length; j++) {
    var coords = json[i].Geom[j];
    //Convert the coordinates to GLatLng and insert into the array
    points.push(new GLatLng(parseFloat(coords[0]), parseFloat(coords[1])));
}

// Create a new instance of PolylineEncoder
var polylineEncoder = new PolylineEncoder();

// Assign the array to dpEncodeToGPolyline  to get an encoded polyline
var polyline = polylineEncoder.dpEncodeToGPolyline(points, '#ff0000', 5, 0.7);

// Add the returned polyline to the map with map.addOverlay()
map.addOverlay(polyline);

The performance boost with this technique is enormous. The loading time can still be quite long but interacting with the map is a totally different experience. Watch the encoded polylines example to see what I mean.

Encode polylines on the server

Loading time could still be too long, especially in Internet Explorer which has a a notoriously slow Javascript engine. To improve on that you should perform the encoding server side. In the second part of this article I describe how to do just that using PHP, to get dramatically shorter load-times.

Further reading

Mark MacClure, as I've already mentioned, has written a lot on the subject and also provides several examples, so don't miss checking Encoding polylines for Google Maps out.

Peter Chng has written an article about encoded polylines, Playing with Google Maps and encoded polylines, that helped clear a lot of my confusion.

My Google Maps book

If you found this article useful you might be interested in my book Beginning Google Maps API 3. It covers everything you need to know to create awesome maps on your web sites. Buy it on Amazon.com