Including the library

First of all to be able to use the library you need to let the Google Maps API know that you want to use it. This is done by adding an extra parameter to the querystring when including the Maps API on the web page.

<script type="text/javascript" src="http://maps.google.com/maps/api/js?libraries=geometry&sensor=true_or_false"></script>

Namespaces

Once you’ve done that you have a number of extra functions that you can use. They all reside in one of two namespaces:

• google.maps.geometry.spherical
• google.maps.geometry.encoding

The spherical namespace includes functions for calculating angles, distances and areas from latitudes and longitudes. These are the functions that we will examine in this article.

The other namespace, encoding, contains functions for encoding and decoding paths for polylines and polygons. They’re useful when you have big sets of data for displaying polylines or polygons that you need to optimize. I will not describe this namespace further here, maybe it’s a subject for a future article.

Note: The library doesn’t consist of any classes but only have static functions.

The earth is round, the map is flat

When calculating distances and areas you need to take the fact that the earth is round into consideration (hence the name spherical). Since a map is flat a straight line on it is in fact an arc. Take a look at the map below. The shortest route between New York and London will look like an arc on a flat map (the blue line in the image below).

A straight line between two point on a map is in fact an arc.

Therefor when calculating distances and areas you need to use some pretty advanced mathematics to do it. Fortunately with the Geometry Library it’s dead simple.

Distances and areas

Calculating the distance

Calculating the distance between two points is really easy with the help of the Geometry library. All you have to do is to call the computeDistanceBetween() function and pass it two LatLng objects.

var nyc = new google.maps.LatLng(40.715, -74.002);
var london = new google.maps.LatLng(51.506, -0.119);
var distance = google.maps.geometry.spherical.computeDistanceBetween(nyc, london);

The function returns the distance in meters. In this case it says that it’s 5 576 673 meters between NYC and London.

Determining the heading

If you also want to know the heading between two points you can use the computeHeading() function. It also takes two LatLng objects and determines the heading from the first to the second.

var nyc = new google.maps.LatLng(40.715, -74.002);
var london = new google.maps.LatLng(51.506, -0.119);
var heading = google.maps.geometry.spherical.computeHeading(nyc, london);

The heading is returned in degrees from the true north (counts clockwise from 0). The heading from NYC to London is 51.2145583127633 degrees.

Calculating an area

To calculate the size of an area there’s the computeArea() function. Unlike the two previous functions it takes an array of LatLng objects as a parameter. The LatLng’s in this array represents a polygon and it must be closed, meaning that it will automatically close the polygon by connection the first and the last LatLng.

Note: You can also pass a MVCArray as a parameter. It’s basically a regular array but is API specific and has a few other advantages.

var nyc = new google.maps.LatLng(40.715, -74.002);
var london = new google.maps.LatLng(51.506, -0.119);
var rio = new google.maps.LatLng(-22.916, -43.251);
var area = google.maps.geometry.spherical.computeArea([nyc, london, rio]);

The code above will calculate the area of a triangle between NYC, London and Rio de Janeiro which is 26 566 710 985 447.367 m²

Navigation functions

There are a few additional functions apart from the ones that calculates distances and areas.

Calculating an end location

If for example, you know the starting point, the distance and the heading. You can get the end location by using the computeOffset() function. It takes the starting point, the distance and the heading as parameters and returns a LatLng object.

If we take the values from the previous examples, the location of NYC, the distance to London and the heading towards London and use them as input.

 var nyc = new google.maps.LatLng(40.715, -74.002);
var distance = 5576673;
var heading = 51.2145;
var endPoint = google.maps.geometry.spherical.computeOffset(nyc, distance, heading);
var marker = new google.maps.Marker({
  position: endPoint,
  map: map
});

In this case endPoint will be the location of London which is LatLng(51.506, -0.118). (it differs slightly because I’ve rounded the numbers)

With the computeOffset() function we can get the end location if we know the starting point, the heading and the distance.

Calculate a point in between

Another useful function is interpolate() which determines a point between two locations based on a fraction between 0 and 1. The fraction represents how far between two locations a point is. So for example 0.5 is a point right in the middle between the start- and end location.

var nyc = new google.maps.LatLng(40.715, -74.002);
var london = new google.maps.LatLng(51.506, -0.119);
var inBetween = google.maps.geometry.spherical.interpolate(nyc, london, 0.5);
var marker = new google.maps.Marker({
  position: inBetween,
  map: map
});

This code will return a position right between NYC and London.

By using interpolate between NYC and London with the fraction 0.5 we get the position right in the middle of those.

Conclusion

Calculating areas and distances on geo data can be tricky, but with the help of the Geometry Library it’s really simple. I hope this article has shed some light on how you can use it in your own map solution.

More resources

To read more about this library, check out the article Google Maps Javascript API V3 Geometry Library in the offical documentation. You’ll also find a description of all the functions in the API documentation.

Using the MarkerManager

The MarkerManager is a very useful Open Source Utility Library for Google Maps with the sole purpose to manage larger amounts of Markers. If you add markers with the MarkerManager you can control at which zoom-levels they will appear. And you can also hide and show them dynamically.

If you want to learn more about the MarkerManager and other libraries out there that deals with markers, read my article Handling Large Amounts of Markers in Google Maps.

Adding markers with the MarkerManager

Now the most effective way to add markers to the MarkerManager is to first add them to an array that you then add to the MarkerManager with the addMarkers() method. The code to do this would be something like this.

// Init the MarkerManager
var mgr = new MarkerManager();
//Defining the array that will contain all markers
var markers = [];
// Creating a marker
var marker = new GMarker(new GLatLng(57.8, 14.0));
// Add marker to the array
markers.push(marker);
// Add the array to the MarkerManager
mgr.addMarkers(markers, 1);
mgr.refresh();

Obviously it’s kind of useless to add only one marker this way. It would only be useful if you had at least a few of them, but I think you get the point.

Hiding and showing markers

In the Google Maps API there are two handy methods to toggle the visibility of markers. These are GMarker.show() and GMarker.hide(). They both work as expected, you call hide() and the markers disappears and then you call show() and the marker is displayed again.

So to hide all markers in this example you simply do this:

// Loop through all markers and hide each of them
for (var i = 0; i < markers.length; i++) {
  var marker = markers[i];
  marker.hide();
}

A bug

There is however one caveat and that is when you zoom the map the markers will magically appear again. This is an annoying bug that only appears when you use it on markers added with an utility library.

Click the image to enlarge

The solution

So far I've only found one solution for this and that is to extend the hide method and tweak the code to place the marker outside the map, thereby making it sort of invisible.

// Saving the position of the marker and then place it outside the map
GMarker.prototype.hide = function() {
  if (this.getPoint().lat() < 90) {
    try {
        this.savePoint = this.getPoint();
        this.setPoint(new GLatLng(90, 0));
    } catch (e) { }
  }
}

Subsequently you need to prototype the show method as well so that it moves the marker into the correct position again.

// Restoring the position of the marker
GMarker.prototype.show = function() {
  if (this.getPoint().lat() == 90) {
    if (this.savePoint) {
      try {
        this.setPoint(this.savePoint);
        this.savePoint = null;
      } catch (e) { }
    }
  }
}

It's a dirty solution I know, but so far it's the best solution I've found and it works really well.

Note: I haven't come up with this solution myself but haven't been able to find where I saw it. So if you know who did come up with it, please tell me so I can give credit where credit is due.

isHidden()

The Google Maps API also offers a method to determain if a marker is hidden or not, GMarker.isHidden(). If you want to be able to use that you have to prototype it as well.

GMarker.prototype.isHidden = function() {
  if (this.getPoint().lat() == 90) {
    return true;
  } else {
    return false;
  }
}

Live examples

Live examples of the bug and the solution

I've put together a few examples of different scenarios using this, so that you will see the problem as well as the solution to it.

• Using GMarker
• Using MarkerManager
• Using MarkerManager - fixed

Other libraries

There are several other libraries for dealing with markers out there, and in at least one of them, Clusterer, I've noticed the same bug as in MarkerManager. The fix proposed in this article will work just fine on that one as well and possibly on other libraries where you might also find this bug.

If you've encountered this problem in other libraries please let me know. It would also be interesting to see other, and possibly more elegant solutions to this problem.

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

In this article I will describe how to create it with the help of jQuery

The basics

The whole idea with this approach is to make the user aware that something has happened, or that an action has been performed. You want to make sure that the message gets across but at the same time you don’t want to annoy the user or get in his or hers way. One way to do this is to show a message across the screen that as soon as the user moves the mouse, clicks a mouse button or press a key on the keyboard fades away.

Watch the live demo

The HTML

The HTML is straightforward. Just insert this code somewhere in your HTML. Preferably at the top or the bottom of it. Just make sure it’s not inside a container with an absolute or relative position.

<div class="message">
    <p>This is a non-modal alert</p>
</div>

Give it some style

We will want the message to hover over the page. Therefor we want it to have an absolute position. By setting the width of the containing <div> to 60% and it’s left position to 20% it’s going to appear centered on the screen.

The other declarations are just for the visual appearance of the message.

.message {
    position: absolute;
    top: 145px;
    width: 60%;
    left: 20%;
    background: #ff9;
    border: 1px solid #fc0;
    font-size: 150%;
    padding: 15px 50px;
}
.message p {
    margin: 0;
    padding: 0 40px 0 20px;
    text-align: center;
}

The Javascript

The Javascript essentially checks if there’s a an element with the class message in the web page. If there is, it attaches a few events on it that when triggered, removes the message.

Notice that I use one() instead of bind() to attach the events. The reason being that once the event is triggered i doesn’t have to trigger again. With one(), jQuery automatically unbinds the event after it’s been triggered.

$(document).ready(function(e) {
    // Check if there's a message
    if($('.message').length) {
         // If mouse is clicked, moved or a key is pressed
         $(document).one('click mousemove keypress', function(e) {
            // Fade the message away after 500 ms
            $('.message').animate({ opacity: 1.0 }, 500).fadeOut();
        });
    }
});

Notice in the part where the alert is faded out, there’s first animate({ opacity: 1.0 }, 500). This is a hack to get a 500 ms long delay before the message starts to fade out. What it actually does is to change the opacity of the element to 1.0 over a timespan of 500 ms. But since the element already has the opacity 1.0 it just creates a 500 ms long delay before the fadeOut() part is executed.

This is all good and works well in most browsers except… you guessed it, Internet Explorer.

Extra tweaks for Internet Explorer

The problem in Internet Explorer is that the mousemove event triggers instantly even if you haven’t moved the mouse. Because of this we have to insert a short delay before the events are attached. In this example I’ve done it by moving the logic to remove the message to a function, removeMessage(), which I call from the setTimeout function. The second argument of setTimeout determains the delay in ms before removeMessage() is invoked.

$(document).ready(function(e) {
     // Check if there's a message
     if($('.message').length) {
         // the timeout is there to make things work properly in IE
         // If we have no timeout IE will trigger mousemove instantly
         setTimeout(removeMessage, 500);
    }
});
function removeMessage(){
    $(document).one('click mousemove keypress', function(e) {
        // Fade the message away after 500 ms
        $('.message').animate({ opacity: 1.0 }, 500).fadeOut();
    });
}

That’s it. Sadly the code is slightly less elegant, but at least i works in all browsers.

Check out the Live demo

Conclusion

I have found this solution to be an excellent way to tell the user what’s going on in an unobtrusive, but still obvious way. I hope that you’ll find it useful too. If you have a more elegant way of overcoming the problem with IE or other ideas on how to enhance this solution, don’t hesitate to tell me.

Checking if the page has subpages

I searched in vain for a method to determine if the current page has any subpages or not. I first assumed that there would be a has_subpages() method, but so far I haven’t found any. Lacking that, I came up with a very crude way of checking it. I explicitly had to try to fetch all the subpages with the function wp_list_pages() and then check if it returned anything. It’s not pretty but it works.

$children = wp_list_pages('&child_of='.$post->ID.'&echo=0');
if($children) {
    // This page has subpages
}

Checking if it’s a parent page or a subpage

The next thing I had to figure out was how to check i the current page is a parent page or a subpage. That’s done with the following code.

if(is_page() && $post->post_parent) {
    // This is a subpage
} else {
    // This a parent page
}

Fetching the submenu

Now I needed a way to fetch the subpages. This is done with the wp_list_pages() function. The tricky part about this is that there’s no way to get both the parent page and the subpages in the same call. So therefor we have to call the function twice. The call also looks a little different depending on if we’re on the parent page or on the subpage.

if(is_page() && $post->post_parent) {
    // This is a subpage
    $children = wp_list_pages("title_li=&include=".$post->post_parent ."&echo=0");
    $children .= wp_list_pages("title_li=&child_of=".$post->post_parent ."&echo=0");
} else if($has_subpages) {
    // This is a parent page that have subpages
    $children = wp_list_pages("title_li=&include=".$post->ID ."&echo=0");
    $children .= wp_list_pages("title_li=&child_of=".$post->ID ."&echo=0");
}

There are other ways of doing this, but the benefit of this approach is that we automatically get class="current_page_item" on the list-item that represents the page that we’re currently on. That’s handy if you want to style that item in any particular way.

Outputting the HTML

The last step is to output the actual HTML. I’ve chosen to output it as an unordered list.

<?php // Check to see if we have anything to output ?>
<?php if ($children) { ?>
<ul class="submenu">
    <?php echo $children; ?>
</ul>
<?php } ?>

Putting it all together

Now it’s time to put all the pieces together. Just put this code in your page template one of the pages in your template, like for example page.php or sidebar.php and you’re good to go. These pages are located in /wp-content/themes/your-theme/.

<?php
$has_subpages = false;
// Check to see if the current page has any subpages
$children = wp_list_pages('&child_of='.$post->ID.'&echo=0');
if($children) {
    $has_subpages = true;
}
// Reseting $children
$children = "";

// Fetching the right thing depending on if we're on a subpage or on a parent page (that has subpages)
if(is_page() && $post->post_parent) {
    // This is a subpage
    $children = wp_list_pages("title_li=&include=".$post->post_parent ."&echo=0");
    $children .= wp_list_pages("title_li=&child_of=".$post->post_parent ."&echo=0");
} else if($has_subpages) {
    // This is a parent page that have subpages
    $children = wp_list_pages("title_li=&include=".$post->ID ."&echo=0");
    $children .= wp_list_pages("title_li=&child_of=".$post->ID ."&echo=0");
}
?>
<?php // Check to see if we have anything to output ?>
<?php if ($children) { ?>
<ul class="submenu">
    <?php echo $children; ?>
</ul>
<?php } ?>

Conclusion

I think that WordPress is an absolutely awesome CMS/Blog engine, but it do lack some handy methods. Fortunately it’s almost always possible to create workarounds. I hope that you will find this useful in your own WordPress Template. Don’t hesitate to tell me if you have a smarter way of doing this.

In this article I will show you how to add different kinds of Info Windows that appear when you click on a marker.

Content

• Basic Info Window
• Info window with tabs
• Info Window containing a Mini map
• Maximizing the Info Window
• Options
• Conclusion and further resources

Basic Info Window

The key method for opening an info window when clicking a marker is GMarker.openInfoWindowHTML(). It takes two arguments, first the text that will appear in the Info Window and secondly an optional object literal containing options you might want to use to configure the Info Window. To learn more about the available options, see Options further down the page.

In the examples for this article you have to click a marker to open the window. This is done by using the GEvent.addListener() method. I will not describe exactly how it works in this article but if you’re unfamiliar with it you can read more about it in the official documentation.

// Init a new map
var map = new GMap2(document.getElementById('map'));
map.addControl(new GSmallMapControl());
map.setCenter(new GLatLng(56.87, 14.80), 11);
// Creating a new marker
var marker = new GMarker(new GLatLng(56.87, 14.80))
// Adding a click-event to the marker
GEvent.addListener(marker, 'click', function() {
  // When clicked, open an Info Window
  marker.openInfoWindowHtml('Some text');
});
// Add marker to map
map.addOverlay(marker);

This code will result in an ordinary map showing a marker which, when you click on it, pops up an Info Window.

Watch live demo

Info Window with Tabs

If you have a lot of information about each marker, more than you can fit inside a normal Info Window, you could use an Info Window with tabs. You simply define each tab as a GInfoWindowTab and add them to an array that you later on add to the marker using the openInfoWindowTabsHtml() method.

// Create an array that will hold the tabs
var tabs = [];
// Create tabs and add them to the array
tabs.push(new GInfoWindowTab('Tab 1', 'Content of tab 1'));
tabs.push(new GInfoWindowTab('Tab 2', 'Content of tab 2'));
// Add tabs to the InfowWindow
marker.openInfoWindowTabsHtml(tabs);

The result is a tabbed Info Window.

Watch Live Demo

Info Window containing a Mini map

The API features an easy method to open up a mini map over the area where the marker is located, showMapBlowup(opts?:GInfoWindowOptions). This method takes an object literal that have two possible parameters, InfoWindowOptions.zoomLevel and InfoWindowOptions.mapType. These lets you determine at what zoom-level the mini map should start and what map type it should show.

GEvent.addListener(marker, 'click', function() {
  // When clicked, open an Info Window with a min map in it
  marker.showMapBlowup();
});

You never thought it would be this easy to do this, did you?

Watch live demo

Maximizing the Info Window

If you have a lot of content to show in you Info Window it could be useful to let the user maximize it. This is easily done using the options maxContent and maxTitle. If you define these you will automatically get a maximize button in your window.

So to make this work just do like this.

marker.openInfoWindowHtml('Click the (+) to maximize me!', {
  maxTitle: 'Maximized Title',
  maxContent: 'Maximized content text.'
});

When you first click the marker an ordinary info window will pop up. When you click the plus sign (+) in it, it will maximize.

Watch live demo

Options

As I’ve mentioned earlier each of the methods that opens an Info Window takes an optional object literal with options. The properties you can use in it are defined in the GInfoWindowOptions class.

All properties doesn’t comply with all kinds of Info Window.

• selectedTab [number]
  Determines which tab should be selected when opening an Info Window. Starts with number 0.
• maxWidth [number]
  Sets the maximum width of the info window. Note: From my observations it seems that the minimum value for this is 249 pixels.
• noCloseOnClick [bool]
  Sets if the info window should be closed when clicking inside the map. Default value is true.
• onOpenFn [Function]
  A function that is called after the info window is opened and the content is displayed.
• onCloseFn [Function]
  A function that is called when the info window is closed.
• zoomLevel [number]
  Determines what zoom level an opened Mini Map should have. Only applicable with showMapBlowUp().
• mapType [GMapType]
  Determines what map type an opened Mini Map should have. Only applicable with showMapBlowUp().
• maxContent [string]
  Determines what content should be showed when an info window is maximized. It can be either an HTML string or an HTML DOM element.
• maxTitle [string]
  Sets the title for the window when it’s maximized. It can be either an HTML string or an HTML DOM element.
• pixelOffset [GSize]
  Specifies a number of pixels to move the info window away from the current GLatLng.

How to use them

The options are passed to the method in an Object Literal. Here’s an example of using the maxWidth property when opening a basic Info Window.

marker.openInfoWindowHtml('Some text', {maxWidth: '250'});

Conclusion and further resources

Info windows are a powerful way of displaying information about certain objects in a map. In this article I have showed you some of the basic ways to use the built in ones in Google Maps. I think you can go a long way with these techniques but if you have special needs there are third party extensions out there that you can use.

It’s beyond the scope of this article to describe how they work, but the first library to check out should be ExtInfoWindow, one of the open source utility libraries for Google Maps. You’ll find documentation and examples at Google Maps API Utility Library. Joe Monahan has also written some about it on the Google Maps API Blog in the article ExtInfoWindow 1.0: Ajax powered, CSS customization.

Mike William at Google Maps API Tutorial has described two other libraries in the tutorials Using the EWindow extension and Using the EBubble extension that also might be useful.

Happy coding!

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

Update [2009-05-06]:This article has been updated with the addition of the utility library MarkerClusterer. The test results in the end of the article and the test page has also been revised.

If you’re new to markers in Google Maps I recommend that you first read Basic operations with markers in Google Maps for an introduction on how to use them.

The Marker Manager – Keeps track of them

Your first option might be to use the MarkerManager since it’s an utility library provided by Google. Rather than adding each marker individually to the map using GMap2.addOverlay() you first add them to the MarkerManager. The MarkerManager keeps track of all your markers. By defining at which zoom-levels each marker should appear you can cluster the markers to reduce the amount being shown at a time.

The MarkerManager is initially a bit slower than just adding markers directly to the map but the added benefit is that you can have more control over them.

You add markers to the MarkerManager with addMarker(GMarker, minZoom, maxZoom?). This method takes three arguments, the first one being the marker you want to add. The two second arguments are optional but define at which zoom-levels the marker will be visible.

A simple example

// Create a new map
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(59.5, 14.0), 6);
// Create a new instance of the MarkerManager
var mgr = new MarkerManager(map);
// Create a new marker
var marker = new GMarker(new GLatLng(59.0, 13.80));
// Add marker to the MarkerManager
mgr.addMarker(marker);

Obviously there’s not much use adding a single marker to the MarkerManager, but if you have hundreds of them, this might be the way to go.

Bulk adding the markers

An even more efficient way of using the MarkerManager is to do a bulk add by first putting all your markers into an array and then add the array to the MarkerManager with the addMarkers(markerArray, minZoom, maxZoom?) method.

// Create a new instance of the MarkerManager
var mgr = new MarkerManager(map);
// Create marker array
var markers = [];
// Loop to create markers and adding them to the MarkerManager
for(var i = 0; i < 50; i += 0.1) {
    var marker = new GMarker(new GLatLng(59.0 + i, 13.80 + i));
    markers.push(marker);
}
// Add the array to the MarkerManager
mgr.addMarkers(markers);
// Refresh the MarkerManager to make the markers appear on the map
mgr.refresh();

Notice that you have to use mgr.refresh() after adding the marker array to it. That's not necessary when adding the markers one by one.

Additional methods

• removeMarker(marker)
  Removes a marker from the MarkerManager
• clearMarkers()
  Removes all markers.
• getMarkerCount(zoom)
  Returns the number of markers at a given zoom-level.

The MarkerManager is a utility library provided by Google. On the URL below you'll find the source code as well as the full documentation and examples.

Google Maps MarkerManager SVN

Marker Light - Markers on a diet

Pamela Fox at Google has made a sample app for what she calls MarkerLight, which render less complex markers, thus increasing performance. The trade-off is that it's really just an image on the map, you can't interact with it. If you don't have the need for interaction this is a really easy way to gain performance, the only difference from the ordinary way of doing it is that you create a MarkerLight instead of a GMarker.

On Pamelas post about MarkerLight she explains why this approach is faster:

The reason GMarker takes so long is that it's actually composed of many DOM elements - foreground, shadow, printable version, clickable area, etc.

If your purpose is visualization, then you can get away with just creating a GOverlay extension like MarkerLight that creates a div with a background URL (or background color, even better!).

- Pamela Fox

Here's how to use it:

map.addOverlay(new MarkerLight(latlng, {image: "red_dot.png"}));

red_dot.png in is the image used for the marker. It's a very small and simple one.

You can try performance with different numbers of markers on Pamelas test page.

Download markerlight.js

Using Marker Light in combination with MarkerManager

You can add the benefits of MarkerLight with the clustering capabilities of the MarkerManager. It's really easy, just combine the two:

mgr.addMarker(new MarkerLight(latlng, {image: "red_dot.png"}));

The reason you should do this is that you can display a different number of markers at different zoom levels. This way you can ensure that not too many markers are displayed at the same time.

Clusterer - Only show what you need

A different approach is to use ACME labs Clusterer. It's a third party library that offers a faster way of adding markers. It's released under the BSD license and is freely available.

It allows faster performance by doing two things.

• Only the markers currently visible actually get created.
• If too many markers would be visible, then they are grouped together into cluster markers.

This lets you have literally thousands of markers on a map while maintaining decent performance. My tests with this approach shows that it's significantly faster than the MarkerManager approach.

Here's how to use it:

// Create a Clusterer object
var clusterer = new Clusterer(map);
// Create marker
var marker = new GMarker(new GLatLng(57.8, 14.0));
// Add marker to the map
clusterer.AddMarker(marker, 'text to infobox');

To remove a marker from the map call clusterer.RemoveMarker(marker).

There's also a few methods to change the behavior of the marker.

• clusterer.SetIcon(GIcon)
  Changes the cluster icon
• clusterer.SetMaxVisibleMarkers(n)
  Sets the threshold marker count where clustering kicks in. Default value is 150.
• clusterer.SetMinMarkersPerCluster(n)
  Sets the minumum number of markers for a cluster. Default value is 5.
• clusterer.SetMaxLinesPerInfoBox(n)
  Sets the maximum number of lines in an info box. Default value is 10.

Download Clusterer2.js

ClusterMarker - Chunk 'em all up

ClusterMarker is a free Javascript library released under the GNU General Public License, that adds clustering capabilities to markers. The unique thing with this library is that it automatically detects markers that intersect each other and cluster these into a single cluster marker.

The images below illustrates how this works

Images by Martin Pearman

The constructor takes two arguments and looks like this:

var cluster = new ClusterMarker(map, options).

map is a reference to the map object and options is an object literal that can have these properties:

• clusterMarkerIcon [GIcon]

  Changes the default cluster marker icon to an icon of your choice.

• markers [array]
  An array with all the markers you want to pass to the ClusterMarker

Apart from these properties you can also use all the other properties of the class. Se the documentation for a complete list.

Here's how to add markers using the ClusterMarker with a minimum amount of code.

var markerArray = [];
// Insert code to fill the markerArray with markers...
// Creating a new cluster by adding the map and the markerarray
var cluster = new ClusterMarker(map, {markers: markerArray});
// Refreshing to show the added markers
cluster.refresh();

This code will insert the markers on the map and cluster them under one icon if they're close enough to each other. For more fine grained control of how it operates there are several methods and properties. For a detailed explanation of how the library works there's excellent documentation on the Clustermarker Project page.

MarkerClusterer - The new kid in town

This utility library is the newest of them all and wasn't around when I originally wrote this article. This library, which is written by Xiaoxi Wu and is part of the Google Maps Open Source Utility Library is easy to use and shows excellent performance.

Like some of the other libraries it reduces the number of visible markers by clustering them together making it easier to get an overview. Watch the image below to see how.

Image by Xiaoxi Wu

It's constructor takes three arguments, the first one being a reference to the map, the second one being an array of GMarkers and the third one being an object literal with options. Only the first one is required.

var markerCluster = new MarkerClusterer(map, markers, opts);

So to add a bunch of markers to the map having the default settings of the MarkerClusterer you do this:

var markers = [];
// Insert code to fill the markerArray with markers...
// Creating a new cluster by adding the map and the array of markers
var markerCluster = new MarkerClusterer(map, markers);

See the documentation for a full explanation of the library and it's capabilities. Also read MarkerClusterer: A Solution to the Too Many Markers Problem on the Google Geo Developer blog for more information.

Download markerclusterer.js

Compare performance

Compare the different techniques on the Test page

Inspired by Pamela Fox testpage for MarkerLight I've set up a test page of my own where you can test the performance of all the different approaches in this article.

The result

I ran a series of test with a few different browsers. In each test I added 500 markers using the different techniques. Between each test I refreshed the browsers. All tests were performed on a PC with a 3.60 GHz Pentium 4 HT processor and 2 Gb RAM running Windows XP.

Note: Since the addition of MarkerClusterer I've ran the tests again and updated the result grid. Some of the web browsers are newer than in the lats test run. See the old test results.

In this test Clusterer2 was the fastest technique of them all. Be aware however that this is not the entire truth since I've only been able to measure how long it takes before the markers are passed to the map, not the actual time until they are visible on the map. When taking this into consideration I find that MarkerClusterer is the fastest technique closely followed by ClusterMarker.

When it comes to browsers the fastest performance is marked with green and the worst performance is marked with red in the result grid. Not surprisingly Internet Explorer is the slowest of the lot. Google Chrome and Safari has the fastest overall performance with their blazing fast Javascript engine.

If you have an idea on how to improve this test to better measure the actual time until the markers are visible on the map, please share in the comments or contact me through the Contact page.

Conclusion

The techniques showed in this article are all fairly easy to implement and works well when you don't have an incredibly large amount of markers. For those occasions where none of these techniques suffice you will have to resort to more extreme measures, like creating a big overlay with all the markers, but that's beyond the scope of this article.

I hope that you'll find these techniques helpful. Happy coding!

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

Adding a marker

A marker is a type of overlay, just as it’s siblings polyline and polygon. To add a basic marker to a Google Map all you have to do is to define it with a coordinate of type GLatLng using the GMarker constructor.

// Init the map
var map = new GMap2(document.getElementById('map'));
map.addControl(new GSmallMapControl());
map.setCenter(new GLatLng(59.5, 14.0), 6);
// Create a marker
var marker = new GMarker(new GLatLng(59.0, 13.80))
// Add the marker to the map
map.addOverlay(marker);

This code will create a map and add a basic marker to it.

Making it draggable

To make the marker draggable is really easy. the GMarker constructor takes options in the form of an object literal as it’s second parameter. You simply add {draggable: true} after the coordinates.

var marker = new GMarker(new GLatLng(59.0, 13.80), {draggable: true});

Voila, the marker is now draggable. This is excellent for applications where you want the user to define places on a map.

Adding a Tooltip

Adding a tooltip is done the same way as making the marker draggable. It’s done using another option called title. It will create the same kind of tooltip that adding the attribute title to HTML-elements does.

var marker = new GMarker(new GLatLng(59.0, 13.80), {
    draggable: true,
    title: 'Drag me'
});

This code will produce a standard tooltip when putting the cursor over the marker.

There are a lot of other options you can add to a marker. For a full list check out the documentation.

Adding an Info Window

An InfoWindow is a great way to show more information about a location. It’s done by adding a click event to the marker with the help of the GEvent class. When the click event is triggered, the InfoWindow is opened using the method GMarker2.openInfoWindow().

// Adding a click event to the marker
GEvent.addListener(marker, "click", function() {
    marker.openInfoWindow('My InfoWindow');
});

The result is a standard GInfoWindow which open up when you click the marker. You can close it by either clicking the closing X in the upper right corner or by clicking somewhere in the map.

GMarker.openInfoWindow is the most basic variant of InfoWindows in the API and can only contain plain text. Other types can contain HTML and have tabs. For a full description of the other options available check out the Documentation.

Preventing InfoWindow offset

When using a combination of drag and drop and infowindow a weird thing can happen. It’s that the InfoWindow stay in the same place while the marker is moved.

To prevent this we have to make sure to close the InfoWindow when initiating the drag and drop operation. This is done by listening to the event with GEvent.addListener and close the window with GMap2.closeInfoWindow().

// Close InfoWindow at dragstart
GEvent.addListener(marker, 'dragstart', function() {
    map.closeInfoWindow();
});

Live example

I’ve put together a live example which contains all the techniques described in this article.

Watch the live example.

Conclusion

Markers is an effective way of displaying places on a map. It has a simple yet powerful set of methods to create interactivity. The techniques described here are just a few of all the things you can do, but I think they’ll provide a good starting point.

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

In this article I will show you how to make Google Maps degrade gracefully by providing a fallback for non-javascript users using the Google Static Maps API.

The map switch

The technique is simple. First you have a Google Static Map on your web page, which in fact is a static image. If Javascript is enabled, the static image is overwritten with a dynamic map.

A Static Google Map is simply an ordinary image, dynamically created at Google and displayed on your webpage. You decide how it will appear by passing arguments in the querystring of the image URL. A sample URL could look like this:

http://maps.google.com/staticmap?center=59.1,14.0&zoom=6&size=420x300&key=YOUR_KEY_HERE

This URL will generate a map that look like this:

From this example it’s quite easy to see the different arguments in the query string:

• center
  Defines the center of the map with a coordinate (x, y)
• zoom
  Sets the zoom-level (1-18)
• size
  Defines the size of the map in pixels (width x height)
• key
  Your Google Maps API key. Note that in the example URL the key is omitted. If you don’t already have one you can sign up for one for free.

The switch

This is easy as pie. Just do as normal. The only difference is that you put an image with the static map inside the <div> for the dynamic map. If the dynamic map is loaded it will automatically replace the content of the <div>.

The HTML will look like this:

<div id="map">
    <img src="http://maps.google.com/staticmap?center=59.1,14.0&zoom=6&size=420x300&key=YOUR_KEY_HERE" alt="" />
</div>

And the Javascript will look something like this:

window.onload = function(){
    if (GBrowserIsCompatible()) {
        // Init the map
        var map = new GMap2(document.getElementById('map'));
        map.setCenter(new GLatLng(59.5, 14.0), 6);
    }
}

And there you have it! A map that degrades gracefully if the user lacks Javascript support.

Note: To avoid that the switch appears as a flicker in the browser I recommend using a DOM-loader that executes after the DOM has been loaded. All major Javascript libraries like jQuery and Prototype has these.

Live example

I’ve constructed an example page to show the concept. In the example I also add markers to the map. To learn how to do this read the article Simple maps with the Google Static Maps API.

Try the live example

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

A basic map

The basic concept is to generate an image by adding a regular image tag <img> to the document and in the src attribute add an URL to Google that generates a map image. In the querystring of the URL you define how the map will appear.

Here’s a basic example:

<img src="http://maps.google.com/staticmap?center=59.1,14.0&zoom=6&size=420x300&key=YOUR_KEY_HERE" alt="" />

which will result in this image:

The parameters used in this example are:

• center
  Defines the center of the map with a coordinate (x, y)
• zoom
  Sets the zoom-level (1-18)
• size
  Defines the size of the map in pixels (width x height)
• key
  Your Google Maps API key. Note that in the example URL the key is omitted. If you don’t already have a key you can sign up for one for free.

Adding markers

The use of markers in the map is quite limited but you can put up to 50 markers on a map in 10 different colors and in 3 different sizes with an optional letter in it on the map. Naturally you can’t interact with them in any way since that requires Javascript.

The basic syntax is:

markers=markerDescriptor1|markerDescriptor2|markerDescriptor3|

Each marker is separated with a pipe character (|). It’s then defined with its coordinates and then with its characteristics: lat, lng, size|color|letter. The last parameter is the most cryptic one since the words are all crammed together. A normal sized red marker with the letter A in it will look like midreda (eg. mid red a).

This code will generate 3 markers with different characteristics. The first one will be a normal red marker with the letter A in it [midreda]. The second one will be small with the color green [smallgreen] and the last one will be really small and orange [tinyorange].

markers=59.0,13.8,midreda|59.35,15.60,smallgreen|59.73,13.12,tinyorange

The parameters in this example are:

• latitude
  The latitude of the markers position.
• longitude
  The longitude of the markers position.
• size
  Defines the size of the marker. Valid values are mid, small, tiny. If none is specified it defaults to mid.
• color
  The marker can have one of 10 different colors Valid colors are: black, brown, green, purple, yellow, blue, gray, orange, red, white. Default is red.
• alphanumeric-character
  An optional character can be placed inside medium sized markers [a-z] [0-9]. Note that small and tiny markers cannot contain a character.

No need for center or zoom

One cool thing with static maps is that if you have markers on it you don’t have to define the center of the map or the zoom-level. It’s automatically calculated for you so all markers will fit. You can of course override it by explicitly defining center and zoom.

Adding paths

A path is a line built up of 2 or more coordinates. To add a path to a static map you use path: with a set of parameters.

There’s two kinds of parameters. The first kind defines the visual look of the path and the second kind the coordinates.

The visual look of a path

There are three parameters for the visual look of a path:

• rgb
  This is a 24-bit hex color value determining the color of the path. For example rgb:0x0000ff. With this parameter you can’t control the opacity of the path which defaults to 50%
• rgba
  This is a 32-bit hex color value determining the color of the path. The last 2 characters sets the alpha channel. For example rgba:0x0000ffff
• weight
  Specifies the thickness of the path in pixels. For example weight:5

The coordinates

A path is made up of 2 or more coordinates. You can currently have up to 100 coordinates for each path. The coordinates are separated by a pipe character (|) like this: 59.0,13.8|59.2,13.9.

A red semi transparent path made up of 5 coordinates would for example look like this

path=rgb:0x0000ff,weight:5|59.0,13.8|59.2,13.9|59.0,13.0|59.5,13.0|58.1,12.8

Note that just like with the markers you don’t need to supply the map with center and zoom level when using a path. The map will automatically display in a way so that the entire path is visible.

Optional parameters

There’s some other things you can do with this API. Here’s some more optional parameters to play around with.

• format
  This paramater lets you determain which image format the returned map should be in. Valid values are: gif, jpg, jpg-baseline, png8, png32. Default value is gif.
• maptype
  Defines the maptype. Possible values are roadmap, satellite, terrain, hybrid, and mobile. The default value is roadmap
• span
  This defines the minimum size of the viewport expressed as a latitude, longitude. The API calculates the appropriate from the center point and the span. If zoom is defined span is ignored.
• frame
  Defines that the image should be framed with a 5px, 55% opacity blue border. Valid values are true or false.
• hl
  Sets the language to be used on tile labels. Not all tiles support different languages, on these the default language is used.
• sensor
  This parameter specifies if the application is using a sensor to determine the users location. Valid values are true or false.

For a full description of the Google Static Maps API, visit the API page at Google.

The Static Map Wizard

If you’re lazy you can use the Static Map Wizard to create the URL for you. It’s an excellent tool making it really easy to create a map with markers and polylines.

It’s done in four easy steps.

1. Find the place on the map you want to show. Draw polylines and insert markers into the map by dragging and dropping.
   
2. Define how you want the map, markers and paths to appear
   
3. Watch the generated image
   
4. Get the created URL
   

   http://maps.google.com/staticmap?center=37.400465,-122.073003&markers=37.404119,-122.061024,brown|37.391436,-122.053299,brown&path=rgba:0xff000099,weight:6|37.39561,-122.08952|37.39125,-122.07064|37.40025,-122.06188|37.40998,-122.10291|37.39561,-122.08952&path=rgba:0xff000099,weight:6|37.38947,-122.10686&zoom=13&size=300x300&key=YOUR_KEY_HERE

Note that you manually have to add your API key at the end of the URL.

Conclusion

The Google Static Maps API is naturally not a replacement for the full Google Maps API. But it can provide basic functionality when you either just want a really simple and lightweight map or when the user doesn’t have Javascript available.

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

This time around I think I’ve got all the details right. Well, if that’s not Kaizen, what is?

The old article

In the original article, Ultimate Site Logo, I described how to code a site logo to meet these needs:

• Search engine optimized
• Clickable
• Accessible
• Looks good
• Hover effect

If you haven’t already read it, this could be a good time to do so to fully grasp the concept. But if you feel confident enough, then by all means, do read on.

The semantic problem

In my first solution I suggested that <h1> would be an appropriate element to host the logo. Even though I already back then felt that a different element could be used, I personally was leaning more towards <h1>.

After reading up a little and listening to remarks from others I have now changed my mind. Especially after reading Chris Pearsons article The Definitive Guide to Semantic Web Markup for Blogs.

I now believe that <h1> should be reserved for the most prominent heading on each individual page. So for the front page, the logo (e.g. site name) might as well be the most prominent one, while on sub pages such as an article page, the articles title should be the most prominent one.

Therefor I now recommend using a div to hold the site logo. The code for this would be:

<div id="branding">
	<div id="logo"><a href="#"><span></span>In usability we trust</a></div>
</div>

Note: I haven’t actually implemented this technique on this site yet, but I will do so in an upcoming redesign. Still you can watch it in action on the example page for this article.

The flicker problem

In my last solution I changed the background-image of the <span> displaying the logo, when hovering over it. The problem with this is that if the hover-image wasn’t cashed, there would be an occasional flicker revealing the text underneath it, before the image was loaded. To solve this issue I now use CSS sprites instead.

A sprite is basically an image that contains several images, in this case two. The trick is to, with the help of CSS, just show a part of it at a time. By aligning the background-image to either the left or the right side of the <span>, a roll-over effect is created.

As you can see this image contains two version of the logo, one in normal state and one in hover-state. By making the container only half the width of the complete image, it’s easy to show the different versions by either aligning the background-image to the left or to the right side of the container.

The logo in it’s normal state, where only the left part of the image is visible in the containing <div> (the red area).

The logo in it’s hover state, where only the right part of the image is visible in the containing <div> (the red area).

The CSS to accomplish this is:

#logo span {
	background: url(../img/logo_sprite.png) left top no-repeat;
}
#logo a:hover span {
	background-position: right top;
}

It was actually a comment from r-doll on a different article of mine that made me realize that CSS-sprites would be the way to go in this solution too. Thanks a lot!

The (almost) complete CSS

I say almost complete because there is two additional Internet Explorer fixes, that is best put in a separate CSS-file only served to IE.

#logo {
	position: relative;
	margin: 0;
	width: 442px;
	height: 125px;
}
#logo a {
	position: absolute;
	width: 100%;
	height: 100%;
}
#logo span {
	position: absolute;
	z-index: 1;
	width: 100%;
	height: 100%;
	background: url(../img/logo_sprite.png) left top no-repeat;
}
#logo a:hover span {
	background-position: right top;
}

Note: For a full explanation of the CSS and the additional fixes needed for IE, read the old article, Ultimate Site Logo.

Further improvements

If you can think of further improvements I would be more than happy if you would share it with me.

One issue that I’m aware of is when printing the web page. The logo just shows if you have print background images turned on, otherwise the text underneath the logo will show. If you have a solution for this, please let me know!

The files

• Watch the live demo
• style.css [The main style sheet]
• ie.css [Style sheet fed to IE alone]