smallworld.js

smallworld.js is a utility for generating map overviews using GeoJSON and HTML Canvas. It was created out of a need to render simple map previews, quickly and efficiently, without strict Terms of Use and without heavy client libraries.

The utility has no dependencies, weighs ~5kb (sans GeoJSON), and also comes with a simple wrapper to use with jQuery or Zepto. The source is available on Github or via Bower:

bower install smallworld.js

Default

Just pass in your GeoJSON source and you're done. By default, maps are centered at [0, 0]. The map will inherit its size from the DOM element you initialize it with. If you're using the same GeoJSON for all of your maps, you can also set the data source as a default.

$('.map').smallworld({
	geojson: data
});

// OR…

Smallworld.defaults.geojson = data;
$('.map').smallworld();

Center & Zoom

Maps can be centered on any geographic coordinate, as well as zoomed. The default zoom level is set to 0.

$('.map').smallworld({
	zoom: 1,
	center: [37.757719928168605, -122.43760000000003]
});

Colors

Maps are drawn on the fly, so changing the color of anything is easy.

$('.map').smallworld({
	center: [45, 0],
	waterColor: '#021019',
	landColor: '#08304b'
});

Markers

You can easily drop markers on the center of the map, or anywhere else by passing in additional coordinates. Markers can also have a custom size and color.

$('.map').smallworld({
	marker: true,
	markerColor: '#fa29df'
});

$('.map').smallworld({
	center: [45, 180],
	marker: [37.757719928168605, -122.43760000000003],
	markerSize: 8
});

$('.map').smallworld({
	center: [45, -50],
	markers: [
		[37.757719928168605, -122.43760000000003],
		[51.528868434293145, -0.10159864999991441],
		[40.705960705452846, -73.9780035]
	],
	markerSize: 8
});

Using without jQuery/Zepto

To use smallworld.js without jQuery or Zepto, initialize it with a DOM element and options.

var el = document.querySelector('.map');
var map = new Smallworld(el, options);

GeoJSON & Technical Notes

smallworld.js provides one drop-in GeoJSON source, the one used in the maps above. The GeoJSON data can be inlined or loaded asynchronously, so long as the data is passed in during initialization or set globally. The provided GeoJSON will be projected using the Mercator projection.

This GeoJSON is generated from Natural Earth's “Small-scale data, 1:110m” data set. The shape files provided by Natural Earth are then processed by ogr2ogr to convert to GeoJSON and simplify paths. You can see this conversion yourself by peeking at this build task. To generate your own GeoJSON with a different level of optimization, play around with the value passed in the “simplify” flag in the build task.

In an effort to keep file size low, the GeoJSON source provided here has been optimized for viewing at zoom levels 0 and 1. While it's theoretically possible to crank the zoom level up infinitely, at a certain point, beyond zoom level 3 or 4, this utility won't be of much use as the maps will become too abstract.