Skip to content

Streaming UTF-Grid json tiles via TileStache

27. March 2013

I have already described some different possibilities for easily attaching interactive information visualisation to tile-based maps in another post. It became clear (at least its my hope ;-)) that, the utilisation of the generalized dataformat ‘UTF-Grid’ is a very good implementation for quick interactive display of additional information with good performance.

The best resources to get an understanding of this kind of generalised/compressed dataformat can be found here and here.

In the previous post, I have only used UTF-Grids that were indirectly created and provided. That means, I made a map using TileMill, exported it and loaded it up to MapBox. Then I was able to request this map directly or indirectly. Indirect means, that I load and display the image- and grid-tiles in an individual Leaflet framework. This was very easy implement- & applicable but the definition of the UTF-Grid is only editable with limitations, predetermined by the GUI of TileMill.

That is why, this post will be focused on the definition and supply of individually defined UTF-Grids using TileStache. As I am not the first one who made that kind of implementation, I owe you some references (general, specific).

TileStache is fundamentally related to Mapnik and therefore is the definition and tiling of the UTF-Grid done by Mapnik and TileStache is just the tile-caching server that provides the required (data-) tiles. Accordingly, Mapnik has to run perfect on your system. That was not true for my Ubuntu 12.04, when I began with this exemplary implementation. The resulting grids were always weary and not usable. Good old Google told me that I am not the only one and this problem is related to the PPA-version of Mapnik. So it is necessary to install Mapnik (Version2) manually from source, than it works perfect.

Let’s begin by setting up TileStache.

This is my startup command:

~/Software/TileStache/scripts/ -c ~/Software/TileStache/press_freedom_utf-gridding.cfg

I am basically using a standard TileStache server definition by calling directly, the original start up file: ’’ located in the installed directory of TileStache.

Accordingly, I just have to define my individual configuration file – press_freedom_utf-gridding.cfg – and the corresponding Mapnik style file – style_press.xml -.

The Configuration file contains information on the:

  • physical cache storage location
  • UTF-Grid and its necessary contents:
    • name of the grid
    • location of style file
    • attributes (fields) that should be integrated to the grid –> this the content the will be interactively visualised
    • scale

…and looks as follows:

    "name": "Disk",
    "path": "/home/klammer/log-files"
        "class": "TileStache.Goodies.Providers.MapnikGrid:Provider", 
            "mapfile": "examples/style_press.xml", 
            "fields":["name", "rank"],
            "layer_index": 0,
            "scale": 4

I do…

  • store the cached files at: “/home/klammer/log-files”,
  • name my grid: “press_freedom_utfgrid”,
  • store the style at: “examples/style_press.xml”,
  • want to display: [“name”, “rank”] and
  • set scale to: 4.

The Mapnik style file contains basically just the information, where the corresponding datasource is located:

<?xml version="1.0"?>

<!-- An ultra simple Mapnik stylesheet -->

<!ENTITY google_mercator "+proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +wktext +over +no_defs">

<Map srs="&google_mercator;">
    <Style name="style">
            <PolygonSymbolizer />
    <Layer name="layer" srs="&google_mercator;">
            <Parameter name="type">shape</Parameter>
            <Parameter name="file">sample_data/world_merc2.shp</Parameter>

In my case it is an ESRI shapefile, but you should be able to use any datasource that Mapnik can handle.

Make sure you are working clean with the definition of projection. In my case source and goal are identical. For example, when your datasource is in LngLat you have to define that within the style file.

After we have defined the two basic files and have linked everything relative and clean, you can start the server and exemplary call your tiles. Here is my startup command:

~/Software/TileStache/scripts/ -c ~/Software/TileStache/press_freedom_utf-gridding.cfg

In my setup, I can call the grid examplary by this command:


When you get no error and see a line that begins like this:

{“keys”: [“”, “87”, “39”, “184”, “163”, “227”, “206”,

…then you have successfully set up TileStache for providing an UTF-Grid.

Within my exemplary implementation I have found out, that you can only offer one UTF-Grid at one time.

The integration to a leaflet webmapping framework is completely similar to that one in my previous post, only the URL and the requested attributes have to be changed.

See an exemplary implementation here. This demo will only work when TileStache is running and providing the corresponding grid!

Leave a Comment

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: