October 24, 2016
Hot Topics:

Creating Custom Overlays with the Google Maps API

  • March 12, 2010
  • By Jason Gilmore
  • Send Email »
  • More Articles »

No matter how complex a Google Maps API implementation is, the application usually is focused on specific locations such as addresses or routes, for instance, the shortest path between two towns. But what if you want to represent spatial data in terms of a larger area, such as the blast radius of a nuclear explosion or the incidence of flu outbreak within major cities (see Figure 1)?

Figure 1. Circular Overlays in Google Maps API:
Here is a circular overlay atop major Ohio cities.

You can accomplish such spatial data representations using a Google Maps API feature known as the custom overlay, a technique I explain in this tutorial.

Creating a Custom Overlay

If you've ever added a marker or charted a route using the Google Maps API, you actually created a custom overlay. An overlay is any foreign object that is situated atop a rendered map. It could be a marker, a shape such as a circle, an image, or even another map or map inset.

AS an example, suppose you wanted to place a 15-mile radius around the center of Columbus, Ohio. Because the API does not offer a way to explicitly add specific objects such as a circle or square to a map, you instead need to calculate all of the points that together comprise the object's outline. Performing such a task requires a bit of a math refresher, as it involves several calculations for determining the points on a circle given a radius and center. This formula is available and discussed in detail on countless web sites, so I'll forego the mathematical explanation and instead show you the JavaScript function used to create the circle:

function drawCircle(lat, lng, radius, stroke, sColor) {
  // Degrees to radians 
  var d2r = Math.PI / 180;
  // Radians to degrees
 var r2d = 180 / Math.PI;
  // Earth radius is 3,963 miles
 var cLat = (radius / 3963) * r2d;
  var cLng = cLat / Math.cos(lat * d2r);
  // Store points in array 
  var points = [];
  // Calculate the points
  // Work around 360 points on circle
  for (var i=0; i < 360; i++) {
    var theta = Math.PI * (i/16);
    // Calculate next X point 
    circleX = lng + (cLng * Math.cos(theta));            
    // Calculate next Y point 
    circleY = lat + (cLat * Math.sin(theta));
    // Add point to array 
    points.push(new GPoint(circleX, circleY));
  // Add points to map 
  map.addOverlay(new GPolyline(points, sColor, stroke));

Therefore, to create a circle around a specific point, you need to pass five parameters to the drawCircle() function:

  • lat: The latitudinal component of the circle's center
  • lng: The longitudinal component of the circle's center
  • radius: The circle's radius
  • stroke: The circle's stroke weight, defined in pixels
  • sColor: The circle's stroke color, defined using hexadecimal format

The API's role in this action is really confined to a single call to the following line:

map.addOverlay(new GPolyline(points, sColor, stroke)); // Add points to map

As you can see, the GPolyline() class instantiator accepts three parameters: the points array, the stroke color, and the stroke width. This object is subsequently passed to map.addOverlay(), the map object having been defined per usual at some previous point in the script. With the drawCircle() function defined, all you need to do is call it, passing along the required parameters.

As an example, the following three calls respectively will plot circles having a radius of 20 miles over Cincinnati, Cleveland, and Columbus, Ohio.

// Cincinnati
drawCircle(39.144972, -84.476623, 20, 5, '#000000');
// Cleveland
drawCircle(41.498806, -81.707382, 20, 5, '#000000');
// Columbus
drawCircle(39.954578, -82.998689, 20, 5, '#000000');

Adding Some Color

While using the GPolyline() function enables you to bring special attention to specific areas on a map, sometimes you'll want to add some extra color to not only raise the profile of a particular area but also perhaps to lend some context to the various locations. For example, suppose you wanted to create a map that depicts the incidence of zombie outbreaks according to a color-coded legend (see Figure 2). To accomplish this, you should use the GPolygon class, which allows you to define both an overlay fill color and opacity.

Figure 2. Color-coded Overlays with the Google Maps API:
You can use color-coded overlays to depict zombie outbreak incidences.

You can achieve this effect by using the previously defined drawCircle() function. Simply swap out the GPolyline() call with the following:

map.addOverlay(new GPolygon(points, sColor, stroke, .50, sColor, .50));

To cut corners, I've reused the sColor value twice. However, as hopefully the parameter pattern indicates, you can control both the shape fill and line independently of one another.

Page 1 of 2

Comment and Contribute


(Maximum characters: 1200). You have characters left.



Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date
Rocket Fuel