API

#Kartograph.js API documentation This documentation refers to an older version of Kartograph. Please see kartograph.org/docs/kartograph.js for up to date docs.

The Kartograph API is stored under the namespace kartograph or the $K shorthand.

Instantiating Kartograph maps

For instantiating Kartograph all you need is a container element, which must exist in the HTML page. Please ensure to run this after the page has been loaded.

map = kartograph.map('#container');
// or
map = $K.map('#container');
// or
map = new kartograph.Kartograph('#container');

By default, Kartograph will use the width/height of the container element. If you want to force different dimensions, you can pass width and height as parameters:

map = kartograph.map('#container',800,600)

Loading SVG maps

The next logical step would be to load a SVG map. You can do so using the loadMap() function. The first parameter is the file name of the SVG file (must be on same domain), the second parameter is the function that should be called once the map is loaded.

map.loadMap('map.svg', function(map) {
	// do something
});

Adding layers to view

The first thing you want to do after the map has been loaded is to set up your map layers. Kartograph SVG maps organize maps in multiple layers. In most cases the layers consist of polygons but other geometries are supported as well (eg. lines for the graticule or circles for cartograms). To identify the layer you need to pass the id property.

map.addLayer("countries");
// or
map.addLayer({ id: "countries" })

If you need Kartograph to identify the polygons of a layer, you can specify a key attribute. For instance, if a SVG map stores ISO3 codes for each polygon (<path data-iso3="USA" .. />, you would add this:

map.addLayer({
	id: "countries",
	key: "iso3"
})

Per default, the layer polygons will get the layer id as CSS class name. If you want to set up a different class name (for instance if you need to add a layer multiple times), you can do so via className attribute:

map.addLayer({
	id: "countries",
	className: "mycountries"
})

Filtering polygons from a layer

map.addLayer({
	id: "countries",
	className: "usa",
	filter: function(d) {
		return d.iso3 == "USA"
	}
})

Symbol maps

new Kartograph.SymbolGroup({
	map: map,
	data: mydata,
	type: "Bubble",
	radius: function(d) { return Math.sqrt(d.value) }
});

Choropleth maps

In choropleth maps, each map region will be colored according to some data value. Again, the data object should be a dictionary of region keys to whatever you want. Kartograph will call the function for every region of the specified layer. If you leave out the layer parameter, the last added layer will be used.

map.choropleth({
	layer: 'countries',
	data: mydata,
	colors: function(d, pathdata) {
		return '#f94'; // return color based on data value/object or path data
	}
});

For more advanced color features like interpolation and color scales I'd suggest to use Chroma.js, which is kind of a side project of Kartograph.

colscale = new chroma.ColorScale({
    colors: ['#F7E1C5', '#6A000B'],
    limits: chroma.limits(mydata, 'quant', 5)
});

map.choropleth({
	layer: 'countries',
	data: mydata,
	colors: function(d) {
		return '#f94'; // return color based on data value/object
	}
});