Cartographer.js

Cartographer

Thematic mapping library for Google Maps. Follow @cartograherjs for updates and new releases.

Download

This is an early stage release. While reasonably stable, you can expect that future versions will contain functionality and API changes.

Download v 0.4 Alpha

Cartographer has been tested with Firefox, Safari, and Internet Explorer. Cartographer.js is licensed under the MIT license. Feedback, bugs, and feature requests can be recorded at the Google Code project page.

Thumbtack, Marketplace for local services. Our awesome sponsor

Use Thumbtack to find trusted local services such as house cleaners in Portland, Oregon.

Demos

Basic configuration

Include the Raphaël and Cartographer scripts. (Cartographer depends on Raphaël for SVG drawing.)

<script type="text/javascript" language="javascript" src="js/raphael-min.js"></script>
<script type="text/javascript" language="javascript" src="js/cartographer.js"></script>

Pass an instance of the Google Map object to Cartographer global variable. A new Cartographer instance will be created an initialized to this map. You need to create one (and only one) instance per map.

Usage:

var map = new GMap2(document.getElementById("map");
// ... adjust Google Map settings here

var options = { colorize:"#fff" };
var cartographer = Cartographer( map, options );
      

Options:

autoZoom
true or false indicating whether to automatically recenter and zoom the map to best fit the thematic elements added by Cartographer. Default is true.
colorize
A hex color string. A layer will be added to the map to add tint and help emphasis the visual components added by Cartographer. Pass null to disable.
colorizeAlpha
Number from 0 to 1.0 indicating the transparency of the colorizing layer.

Methods:

Any Cartographer object has the following methods.

choropleth
Add color-coded regions to the map.
cluster
Create a cluster map.
pies
Add pie charts to the map.
scatter
Create a scatter map.

Types of maps

Cartographer supports a number of standard thematic map types.

Choropleth

Choropleth maps—sometimes known as heatmaps—color regions or polygons based on values. (info on Wikipedia) Cartographer uses pre-encoded polygons to enhance rendering speeds. US states and counties are supported, see the demo page for more information.

Usage:

var data = [ 
  { region:"US-CA", val:10 },
  { region:"US-OR", val:15 },
  { region:"US-WA", val:20 } 
];

// here we specify a custom color scheme
var options = { colors: ["#000","999","#fff"] };

cartographer.choropleth( data, options );
      

Options:

colorScheme
One of the standard Cartographer color schemes.
colors
A custom color scheme specified as an array of hex colors. e.g., [ "#ff00aa", "#00ffaa", "#00aaff" ]
reverseColors
Boolean, true or false.

Pie charts

Show a set of pie charts at specified latititude/longitude points.

Usage:

// lat, lng, pie-size, values segmented by categories
var data = [
  [ 20, 20, 30, [3,6,10,4, 0, 0] ],
  [ 30, 21, 30, [3,6,10,4,10, 0] ],
  [ 40, 35, 30, [3,6,10,4, 8, 4] ],
  [ 55, 30, 30, [3,6,10,4, 0,15] ] 
];
cartographer.pies( data );
      

Options:

colorScheme
One of the standard Cartographer color schemes.
colors
A custom color scheme specified as an array of hex colors. e.g., [ "#ff00aa", "#00ffaa", "#00aaff" ]
reverseColors
Boolean, true or false.
stroke
Stroke color around the pie chart and between segments specified as a hex string, e.g. #ff0000.
opacity
Value between 0 and 1.0.

Cluster map

Area scaled circles that represent clusters of points. Zooming in or out will re-cluster the points. Useful for large quantities of points. Individual points can contain unique values that will be summed to equal the value for a particular item in the cluster. Info balloons will be created as an ordered list of all the labels in the data set for a particular cluster.

Usage:

var data = [
  { lat:8, lng:20, val:3, label:"Item 1" },
  { lat:8, lng:-23, val:10, label:"Item 2" },
  { lat:8, lng:-26, val:10, label:"Item 3" },
  { lat:8, lng:-28, val:10, label:"Item 4" },
];
var options = { color:"#AA00FF", enableGrid:true };
cartographer.cluster( data, options );
      

Custom info balloons:

var data = [
  { lat:8, lng:20, val:3, label:"Item 1" },
  { lat:8, lng:-23, val:10, label:"Item 2" },
  { lat:8, lng:-26, val:10, label:"Item 3" },
  { lat:8, lng:-28, val:10, label:"Item 4" },
];
var customBalloon = function(items) { 
  var html = "Current items:";
}
var options = { color:"#AA00FF", enableGrid:true, balloon:customBalloon };
cartographer.cluster( data, options );
      

Options:

color
A hex string, color for the area-scaled circles.
colorHover
Color to use when mouse is hovering over area-scaled circles.
stroke
Stroke color on the area-scaled circles.

opacity
Value from 0 to 1.0 indicating opacity.
enableDots
Whether to render area-scaled circles. Boolean, true or false. Default true.
enableGrid
Whether to render the underlying grid. Grid squares are tinted based on their values. Boolean, true or false. Default false.
combine
A function with two paramaters that indicates how to combine values as they fall into a grid cell. The default is a summation, function(a,b) { return a + b; }. To average values, use function(a,b) { return .5 * (a+b); }.
gridSize
Points in the cluster map are clustered based on whether they fall in the same grid cell. Change gridSize to ajust the resolution of the visible data. Note that small grid sizes can cause performance issues.
gridColor
If the grid is enabled, this indicates its color.
average
Boolean, true or false. Default is true. If set, will center the area-scaled circles not in the center of a grid cell but at an average point for that cluster, weighted by point values.
balloon
A function that returns HTML for the infoWindow balloon for the current grid cell. The function should take one argument, an array of objects in the current grid cell. Each object has the properties that you passed in to the cluster method, such as lat, lng, val, and label.