Find file
Fetching contributors…
Cannot retrieve contributors at this time
133 lines (100 sloc) 4.59 KB

Windshaft map tiler

A Node.js based webmercator map tile server for PostGIS with Carto map styling API.

  • Pluggable routing to provide customizable tile API URL endpoints
  • Before and after filters to allow custom access control and caching strategies
  • Can render all table data, or data restricted by SQL query
  • Generates image and UTFGrid interactivity tiles
  • Accepts, stores, serves, and applies map styles written in the Carto markup language (same markup as Mapbox Tilemill)
  • Accepts custom map styles on a per tile basis in the tile request
  • Allows setting of CORS headers to allow access to tile data from Javascript
  • No multi layer or composite support yet
Puma Concolor by @eightysteele

Being a dynamic map renderer, windshaft commits some map server 'sins' in it's raw form. The idea is that you the developer will want to graft your own auth/metrics/caching/scaling on top of decent core components. Same old story: high cohesion, low coupling makes us happy.

Windshaft is a library used by, an Open Source Geospatial Database on the Cloud.


  • supports single layer render only.
  • for speed, expects geometry projected to webmercator (EPSG:3857) in a column called the_geom_webmercator.
  • Mapnik is a fast moving target. This currently is pinned to the Mapnik 2.0 release.


  • Node 0.4.x & npm
  • Mapnik 2.0
  • PostgreSQL >8.3.x, PostGIS >1.5.x
  • Redis >2.2.x


npm install windshaft


var Windshaft = require('windshaft');

// Configure pluggable URLs
// =========================
// The config object must define grainstore config (generally just postgres connection details), redis config,
// a base url and a function that adds 'dbname' and 'table' variables onto the Express.js req.params object.
// In this example, the base URL is such that dbname and table will automatically be added to the req.params
// object by express.js. req2params can be extended to allow full control over the specifying of dbname and table,
// and also allows for the req.params object to be extended with other variables, such as:
// * sql - custom sql query to narrow results shown in map)
// * geom_type - specify the geom type (point|polygon) to get more appropriate default styles
// * cache_buster - forces the creation of a new render object, nullifying existing metatile caches
// * interactivity - specify the column to use in the UTFGrid interactivity layer (defaults to null)
// * style - specify map style in the Carto map language on a per tile basis
// the base url is also used for persisiting and retrieving map styles via:
// GET  base_url + '/style' (returns a map style)
// POST base_url + '/style' (allows specifying of a style in Carto markup in the 'style' form variable).
// beforeTileRender and afterTileRender could be defined if you want yo implement your own tile cache policy. See
// an example below

var config = {
        base_url: '/database/:dbname/table/:table',
        req2params: function(req, callback){callback(null,req)},
        grainstore: {datasource: {user:'postgres', host: '', port: 5432}}, //see grainstore npm for other options
        redis: {host: '', port: 6379},
        // this two filters are optional
        beforeTileRender: function(req, res, callback) {
        afterTileRender: function(req, res, tile, headers, callback) {
            callback(null, tile, headers);

// Initialize tile server on port 4000
var ws = new Windshaft.Server(config);
console.log("map tiles are now being served out of: http://localhost:4000" + config.base_url + '/:z/:x/:y.*');

// Specify .png, .png8 or .grid.json tiles.

See examples directory for running server and maptile viewer

Installing Mapnik 2.0




There may be ubuntu ppa's out there with stable 2.0 packages right now - but beware, windshaft requires the official 2.0 release, not a nightly or head version.


Windshaft has a unit and acceptance test suite. To run them, please read ./test/

Thanks to the Mapnik and Mapbox team for making such flexible tools