TileStache API

TileStache is a Python-based server application that can serve up map tiles based on rendered geographic data. You might be familiar with TileCache the venerable open source WMS server from MetaCarta. TileStache is similar, but we hope simpler and better-suited to the needs of designers and cartographers.

This document covers TileStache version 1.7.2.

See also detailed module and class reference.

Requesting Tiles

Over HTTP

TileStache URLs are based on a simplified TMS scheme: 

/{layer name}/{zoom}/{column}/{row}.{extension}

An example tile URL might look like this: 

http://example.org/path/tile.cgi/streets/12/656/1582.png

Interactive, slippy-map previews of tiles are also available: 

/{layer name}/preview.html

In Code

TileStache.getTile

Get a type string and tile binary for a given request layer tile.

Arguments to getTile:

layer
Instance of Core.Layer to render.
coord
One ModestMaps.Core.Coordinate corresponding to a single tile.
extension
Filename extension to choose response type, e.g. "png" or "jpg".

Return value of getTile is a tuple containing a mime-type string such as "image/png" and a complete byte string representing the rendered tile.

See TileStache.getTile documentation for more information.

TileStache.requestHandler

Generate a mime-type and response body for a given request. This is the function to use when creating new HTTP interfaces to TileStache.

Arguments to requestHandler:

config
Required file path string for a JSON configuration file or a configuration object with cache, layers, and dirpath properties, such as TileStache.Config.Configuration.
path_info
Required end portion of a request URL including the layer name and tile coordinate, e.g. "/roads/12/656/1582.png".
query_string
Optional, currently-unused placeholder for possible future query string use. Or maybe an explicit deterrent from ever building such a thing. Hard to say.

Return value of requestHandler is a tuple containing a mime-type string such as "image/png" and a complete byte string representing the rendered tile.

See TileStache.requestHandler documentation for more information.

Serving Tiles

We currently provide three scripts for serving tiles: one for a WSGI-based webserver, one for a CGI-based webserver, and one for Apache mod_python.

WSGI

TileStache comes with a WSGI application and a Werkzeug web server. To use the built-in server, run tilestache-server.py, which (by default) looks for a config file named tilestache.cfg in the current directory and then serves tiles on http://1.7.2.1:8080/. Check tilestache-server.py --help to change these defaults.

Alternatively, any WSGI server can be pointed at an instance of TileStache.WSGITileServer. Here's how to use it with gunicorn: 

$ gunicorn "TileStache:WSGITileServer('/path/to/tilestache.cfg')"

See TileStache.WSGITileServer documentation for more information.

CGI

Using TileStache through CGI supports basic tile serving, and is useful for simple testing and low-to-medium traffic websites. This is a complete, working CGI script that looks for configuration in a local file called tilestache.cfg: 

#!/usr/bin/python
import os, TileStache
TileStache.cgiHandler(os.environ, 'tilestache.cfg', debug=True)

See TileStache.cgiHandler documentation for more information.

mod_python

Using TileStache through mod_python improves performance by caching imported modules, but must be configured via the Apache webserver config. This is a complete example configuration for a webserver publishing tiles configured by a file in /etc: 

<Directory /var/www/tiles>
  AddHandler mod_python .py
  PythonHandler TileStache::modpythonHandler
  PythonOption config /etc/tilestache.cfg
</Directory>

See TileStache.modPythonHandler documentation for more information.

Configuring TileStache

TileStache configuration is stored in JSON files, and is composed of two main top-level sections: "cache" and "layers". There are examples of both in this minimal sample configuration: 

{
  "cache": {"name": "Test"},
  "layers": {
    "ex": {
        "provider": {"name": "mapnik", "mapfile": "style.xml"},
        "projection": "spherical mercator"
    } 
  }
}

Caches

A Cache is the part of TileStache that stores static files to speed up future requests. A few default caches are shown here, with additional cache classes defined in TileStache.Goodies.Caches

Test

Simple cache that doesn’t actually cache anything.

Activity is optionally logged, though.

Example configuration: 

{
  "cache": {
    "name": "Test",
    "verbose": True
  },
  "layers": { … }
}

Test cache parameters:

verbose
Optional boolean flag to write cache activities to a logging function, defaults to False if omitted.

See TileStache.Caches.Test documentation for more information.

Disk

Caches files to disk.

Example configuration: 

{
  "cache": {
    "name": "Disk",
    "path": "/tmp/stache",
    "umask": "0000",
    "dirs": "portable",
    "gzip": ["xml", "json"]
  },
  "layers": { … }
}

Disk cache parameters:

path
Required local directory path where files should be stored.
umask
Optional string representation of octal permission mask for stored files. Defaults to "0022".
dirs
Optional string saying whether to create cache directories that are safe or portable. For an example tile 12/656/1582.png, "portable" creates matching directory trees while "safe" guarantees directories with fewer files, e.g. 12/000/656/001/582.png. Defaults to "safe".
gzip
Optional list of file formats that should be stored in a compressed form. Defaults to ["txt", "text", "json", "xml"]. Provide an empty list in the configuration for no compression.

If your configuration file is loaded from a remote location, e.g. http://example.com/tilestache.cfg, the path must be an unambiguous filesystem path, e.g. "file:///tmp/cache".

See TileStache.Caches.Disk documentation for more information.

Additional Caches

New caches with functionality that’s not strictly core to TileStache first appear in TileStache.Goodies.Caches.

LimitedDisk

Cache that stores a limited amount of data. This is an example cache that uses a SQLite database to track sizes and last-read times for cached tiles, and removes least-recently-used tiles whenever the total size of the cache exceeds a set limit. See TileStache.Goodies.Caches.LimitedDisk for more information.

Layers

A Layer represents a set of tiles in TileStache. It keeps references to providers, projections, a Configuration instance, and other details required for to the storage and rendering of a tile set.

Example layer configuration: 

{
  "cache": …,
  "layers": 
  {
    "example-name":
    {
      "provider": { … },
      "metatile": { … },
      "preview": { … },
      "stale lock timeout": …,
      "projection": …
    }
  }
}

The public-facing URL of a single tile for this layer might look like this: 

http://example.com/tilestache.cgi/example-name/0/0/0.png

Shared layer parameters:

provider
Refers to a Provider, explained in detail under Providers.
metatile
Optionally makes it possible for multiple individual tiles to be rendered at one time, for greater speed and efficiency. This is commonly used for bitmap providers such as Mapnik. See Metatiles for more information.
preview
Optionally overrides the starting point for the built-in per-layer slippy map preview, useful for image-based layers where appropriate. See Preview for more information.
projection
Names a geographic projection, explained in Projections. If omitted, defaults to "spherical mercator".
stale lock timeout
An optional number of seconds to wait before forcing a lock that might be stuck. This is defined on a per-layer basis, rather than for an entire cache at one time, because you may have different expectations for the rendering speeds of different layer configurations. Defaults to 15.

Providers

A Provider is the part of TileStache that stores static files to speed up future requests. A few default providers are shown here, with additional provider classes defined in TileStache.Goodies.Providers

Mapnik

Built-in Mapnik provider, renders map images from Mapnik XML files.

Example Mapnik provider configuration: 

{
  "cache": { … }.
  "layers":
  {
    "roads":
    {
      "provider":
      {
        "name": "mapnik", 
        "mapfile": "style.xml"
      }
    }
  }
}

Mapnik provider parameters:

mapfile
Required local file path to Mapnik XML file.

See TileStache.Providers.Mapnik for more information.

Proxy

Proxy provider, to pass through and cache tiles from other places.

Example Proxy provider configuration: 

{
  "cache": { … }.
  "layers":
  {
    "roads":
    {
      "provider":
      {
        "name": "proxy", 
        "url": "http://tile.openstreetmap.org/{Z}/{X}/{Y}.png"
      }
    }
  }
}

Proxy provider parameters:

url
Optional URL template for remote tiles, for example: "http://tile.openstreetmap.org/{Z}/{X}/{Y}.png"
provider
Optional provider name string from Modest Maps built-ins. See ModestMaps.builtinProviders.keys() for a list. Example: "OPENSTREETMAP".

See TileStache.Providers.Proxy for more information.

URL Template

Templated URL provider, to pass through and cache tiles from WMS servers.

Example UrlTemplate provider configuration: 

{
  "cache": { … }.
  "layers":
  {
    "roads":
    {
      "provider":
      {
        "name": "url template", 
        "template": "http://example.com/?bbox=$xmin,$ymin,$xmax,$ymax"
      }
    }
  }
}

UrlTemplate provider parameters:

template
String with substitutions suitable for use in string.Template. The variables available for substitution are width, height (in pixels), srs (in PROJ.4 format), xmin, ymin, xmax, ymax (in projected map units), and zoom. Example: "http://example.com/?bbox=$xmin,$ymin,$xmax,$ymax&bboxSR=102113&size=$width,$height&imageSR=102113&format=jpg&f=image".

See TileStache.Providers.UrlTemplate for more information.

Additional Providers

New providers with functionality that’s not strictly core to TileStache first appear in TileStache.Goodies.Providers.

Grid

Grid rendering for TileStache. UTM provider draws gridlines in tiles, in transparent images suitable for use as map overlays. See TileStache.Goodies.Providers.Grid for more information.

PostGeoJSON

Provider that returns GeoJSON data responses from PostGIS queries. This is an example of a provider that does not return an image, but rather queries a database for raw data and replies with a string of GeoJSON. For example, it’s possible to retrieve data for locations of OpenStreetMap points of interest based on a query with a bounding box intersection. See TileStache.Goodies.Providers.PostGeoJSON for more information.

SolrGeoJSON

Provider that returns GeoJSON data responses from Solr spatial queries. This is an example of a provider that does not return an image, but rather queries a Solr instance for raw data and replies with a string of GeoJSON. See TileStache.Goodies.Providers.SolrGeoJSON for more information.

Composite

Layered, composite rendering for TileStache. See TileStache.Goodies.Providers.Composite for more information.

Projections

A Projection defines the relationship between the rendered tiles and the underlying geographic data. Generally, just one popular projection is used for most web maps, "spherical mercator".

Provided projections:

spherical mercator
Projection for most commonly-used web map tile scheme, equivalent to EPSG:900913. The simplified projection used here is described in greater detail at openlayers.org.
WGS84
Unprojected projection for the other commonly-used web map tile scheme, equivalent to EPSG:4326.

You can define your own projection, with a module and object name as arguments: 

"layer-name": {
    ...
    "projection": "Module:Object",
}

The object must include methods that convert between coordinates, points, and locations. See the included mercator and WGS84 implementations for example. You can also instantiate a projection class using this syntax: 

"layer-name": {
    ...
    "projection": "Module:Object()"
}

See TileStache.Geography for more information.

Metatiles

Metatiles are larger areas to be rendered at one time, often used because it’s more efficient to render a large number of contiguous tiles at once than each one separately.

Example metatile configuration: 

{
  "cache": …,
  "layers": 
  {
    "example-name":
    {
      "provider": { … },
      "metatile": 
      {
        "rows": 4,
        "columns": 4,
        "buffer": 64
      }
    }
  }
}

This example metatile is four rows tall and four columns wide with a buffer of 64 pixels, for a total bitmap size of 4 × 256 + 64 × 2 = 1152.

Metatile parameters:

rows
Height of the metatile measured in tiles.
columns
Width of the metatile measured in tiles.
buffer
Buffer area around the metatile, measured in pixels. This is useful for providers with labels or icons, where it’s necessary to draw a bit extra around the edges to ensure that text is not cut off.

Preview

TileStache includes a built-in slippy map preview, that can be viewed in a browser using the URL /{layer name}/preview.html, e.g. http://example.org/example-name/preview.html. The settings for this preview are completely optional, but can be set on a per-layer basis for control over starting location and file extension.

Example preview configuration: 

{
  "cache": …,
  "layers": 
  {
    "example-name":
    {
      "provider": { … },
      "preview": 
      {
        "lat": 37.80439,
        "lon": -122.27127,
        "zoom": 15,
        "ext": "jpg"
      }
    }
  }
}

This example preview displays JPG tiles, and is centered on 37.80439, -122.27127 at zoom 15.

Preview parameters:

lat
Starting latitude in degrees.
lon
Starting longitude in degrees.
zoom
Starting zoom level.
ext
Filename extension, e.g. "png".

Extending TileStache

TileStache relies on duck typing rather than inheritance for extensibility, so all guidelines for customization below explain what methods and properties must be defined on objects for them to be valid as providers, caches, and configurations.

Providers

Example external provider configuration: 

{
  "cache": …,
  "layers": 
  {
    "example-name":
    {
      "provider":
      {
        "class": "Module.Classname",
        "kwargs": {"frob": "yes"}
      }
    }
  }
}

The class value is split up into module and classname, and dynamically included. If this doesn’t work for some reason, TileStache will fail loudly to let you know. The kwargs value is fed to the class constructor as a dictionary of keyword args. If your defined class doesn’t accept any of these keyword arguments, TileStache will throw an exception.

A provider must offer at least one of two methods for rendering map areas: renderTile or renderArea. A provider must also accept an instance of Layer as the first argument to its constructor.

Return value of both renderTile and renderArea is an object with a save method that can accept a file-like object and a format name, typically an instance of the PIL.Image object but allowing for creation of providers that save text, raw data or other non-image response.

A minimal provider stub class: 

class ProviderStub:

  def __init__(self, layer):
    # create a new provider for a layer
    raise NotImplementedError
    
  def renderTile(self, width, height, srs, coord):
    # return an object with a PIL-like save() method for a tile
    raise NotImplementedError
    
  def renderArea(self, width, height, srs, xmin, ymin, xmax, ymax, zoom):
    # return an object with a PIL-like save() method for an area
    raise NotImplementedError

See TileStache.Providers for more information on custom providers and TileStache.Goodies.Providers for examples of custom providers.

provider.renderTile

Draws a single tile at a time.

Arguments to renderTile:

width
Pixel width of tile, typically 256.
height
Pixel height of tile, typically 256.
srs
Projection as Proj4 string. "+proj=longlat +ellps=WGS84 +datum=WGS84" is an example, see TileStache.Geography for actual values.
coord
Coordinate object representing a single tile.

Return value of renderTile is a PIL.Image or other saveable object, used like this: 

provider.renderTile(…).save(file, "XML")

provider.renderArea

Draws a variably-sized area, and is used when drawing metatiles.

Non-image providers and metatiles do not mix. If your provider returns JSON, plaintext, XML, or some other non-PIL format, implement only the renderTile method.

Arguments to renderArea:

width
Pixel width of tile, typically 256.
height
Pixel height of tile, typically 256.
srs
Projection as Proj4 string. "+proj=longlat +ellps=WGS84 +datum=WGS84" is an example, see TileStache.Geography for actual values.
xmin
Minimum x boundary of rendered area in projected coordinates.
ymin
Minimum y boundary of rendered area in projected coordinates.
xmax
Maximum x boundary of rendered area in projected coordinates.
ymax
Maximum y boundary of rendered area in projected coordinates.
zoom
Zoom level of final map. Technically this can be derived from the other arguments, but that’s a hassle so we’ll pass it in explicitly.

Return value of renderArea is a PIL.Image or other saveable object, used like this: 

provider.renderArea(…).save(file, "PNG")

provider.getTypeByExtension

A provider may offer a method for custom response types, getTypeByExtension. This method returns a tuple with two strings: a mime-type and a format.

Arguments to getTypeByExtension:

extension
Filename extension string, e.g. "png", "json", etc.

Caches

Example external provider configuration: 

{
  "cache":
  {
    "class": "Module.Classname",
    "kwargs": {"frob": "yes"}
  },
  "layers": { … }
}

The class value is split up into module and classname, and dynamically included. If this doesn’t work for some reason, TileStache will fail loudly to let you know. The kwargs value is fed to the class constructor as a dictionary of keyword args. If your defined class doesn’t accept any of these keyword arguments, TileStache will throw an exception.

A cache must provide all of these four methods: lock, unlock, read, and save.

Each method requires three arguments:

layer
Instance of a layer.
coord
Single Coordinate that represents a tile.
format
String like "png" or "jpg" that is used as a filename extension.

The save method accepts an additional argument before the others:

body
Raw content to save to the cache.

A minimal cache stub class: 

class CacheStub:

  def lock(self, layer, coord, format):
    # lock a tile
    raise NotImplementedError

  def unlock(self, layer, coord, format):
    # unlock a tile
    raise NotImplementedError

  def read(self, layer, coord, format):
    # return raw tile content from cache
    raise NotImplementedError
  
  def save(self, body, layer, coord, format):
    # save raw tile content to cache
    raise NotImplementedError

See TileStache.Caches for more information on custom caches and TileStache.Goodies.Caches for examples of custom caches.

Configuration

A complete configuration object includes cache, layers, and dirpath properties:

cache
Cache instance, e.g. TileStache.Caches.Disk etc. See TileStache.Caches for details on what makes a usable cache.
layers
Dictionary of layers keyed by name.
dirpath
Local filesystem path for this configuration, useful for expanding relative paths.

When creating a custom layers dictionary, e.g. for dynamic layer collections backed by some external configuration, these dictionary methods must be provided for a complete collection of layers:

keys
Return list of layer name strings.
items
Return list of (name, layer) pairs.
__contains__
Return boolean true if given key is an existing layer.
__getitem__
Return existing layer object for given key or raise KeyError.

A minimal layers dictionary stub class: 

class LayersStub:

  def keys(self):
    # return a list of key strings
    raise NotImplementedError

  def items(self):
    # return a list of (key, layer) tuples
    raise NotImplementedError

  def __contains__(self, key):
    # return True if the key is here
    raise NotImplementedError
  
  def __getitem__(self, key):
    # return the layer named by the key
    raise NotImplementedError