Cartographer.js – thematic mapping for Google Maps

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.

Our awesome sponsor

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

Demos

Where is Twitter? – map of 250,000 Twitter users.
10,000 Twitter users – area-scaled circles showing a distribution of Twitter users around the globe.
Benzene concentrations – area-scaled circles visualizing relative benzene pollutant levels from EPA data.
California county populations – California county populations on a log scale.
State Populations – data from the US Census: 2008 state population estimates, rendered on a choropleth map.

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
Pie charts
Point clusters

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:";
  for( var i = 0, ii = items.length; i < ii; i++ ) { 
    html += "" + item.label + " (" + item.val + ")";
  }
  return html + "";
}
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.