7 steps to mapping your story for impact with TileMill and MapBox

February 5, 2014

“I am told there are people who do not care for maps, and I find it hard to believe.”
–Robert Louis Stevenson, author of Treasure Island

I really do love a good map, which is why I am thrilled that producing good maps showing your own data is easier than ever before. In this post, I will explain how to create an interactive map like the one we created showing reported lake and beach closures due to toxic algae for a recently released report and corresponding website on the issue. This was an effective way to share complex information in one glance, and win new media attention to the problem.

Until recently, producing a good looking static or interactive map required expensive software and advanced skills. But now, anyone with some basic technical aptitude and the willingness to learn a new skill can produce a high impact map in a matter of a few hours.

There are many tools are available at a variety of price points. I will focus on one set: MapBox, an online map hosting service, and TileMill, a desktop application for creating map layers. They are designed to work together, though they can be used independently (you can make simple maps online with MapBox, and you can make map images, or map layers for other mapping tools with TileMill.) TileMill is free to use, and MapBox is a “freemium” service — a basic account has a limited number of map monthly map views, and plans are available starting at $5/ month. MapBox and TileMill are used by NPR, Greenpeace, Pew Research and the Guardian.

Step 1: Planning

Before you start out, you should consider whether the data you have will be enhanced by a map. Is your data tied to a place, and will putting it in a geographic context make it easier to understand? For example, comparing two or more neighboring states or countries using a map can be helpful, but comparing two countries that are nowhere near each other is less useful. NTEN has a great article on about map design that showcases specific types of maps, and can give you a sense of whether a map is the right tool for visualizing your data.

Step 2: Collecting Your Datasets and Geocoding

You may have a dataset already, for example, a list of buildings with addresses, or counties with demographic data. Your dataset will need to have coordinates for each point in the case of buildings or addresses, or shape data for boundaries like counties. Getting coordinates is called geocoding, and depending on the type and accuracy of your data, this can be done in an automated fashion, or you might need to do it manually. If you have accurate street addresses, there are a number of tools you can use for geocoding, including this macro that works with Google Drive Spreadsheets and Mapquest’s geocoding service. For the example of counties, you may need to merge or join your dataset with the data from a county shapefile.

Step 3: Finding additional Map Layers

Once you have your dataset(s), you need to determine the basemap and/or map layers that you want to use.  There are many maps available for use for free from governments, academic institutions, and map services like MapBox. TileMill ships with a countries map layer, if you would like to use state, county or US Congressional district boundaries, you can download them from the US Census Department Website. If there is some other layer you are looking for, like watersheds, demographics by census tract, or other political designations, you can often find them through some google searching. After you upload your new layer to mapbox, you can select from a variety of layers including satellite, terrain, buildings and streets.

Step 4: Install TileMill & Create MapBox Account

You could actually do this first, but you can’t go any further until you Download and install TileMill, and create an account on MapBox. At this point, I will mention that if you have a simple map with only a few data points, you may not need to use Tilemill and you can import your geocoded dataset directly to Mapbox and style them there.

There is a caveat: you can make a simpler map by importing your geocoded data directly to MapBox after you have created an account there. Once in MapBox, you can style your map markers, and add tool-tips for each marker. You can also change some of the background map styles. This can be a useful route to take if you have a small number of map points, and do not need to shade countries, states or counties — what in map speak are called “polygons.” We made a map like this for the New Building Institute.

Step 5: Import Your Dataset and Any Other Map Layers

To start working on your map layers in TileMill, you will Import your dataset(s) and any other map layers you want to use (like state or county boundaries).

One important thing to know about TileMill, and this is something that distinguishes it from most commercial GIS software, is that you cannot edit your data once you have imported it.  If you have a typo in a place name in the data you imported, or if you need to add a datapoint, you will need to fix that in your data file and re-import it.

Step 6: Styling Your Map

Now that all of your data and map layers are in TileMill, you can get started with styling your map. TileMill’s online tutorial documentation is very clear and easy to follow on the topic of map syling. TileMill uses a cascading style sheet system similar in structure to CSS, called CartoCSS.  CartoCSS allows you to set color, opacity, thickness, size of map layers, boundaries and markers. You can also set specific map symbolizers.  Even if you are unfamiliar with CSS, the documentation should help you pick it up very quickly.  Once you have your map layer(s) showing your data, you may want to create a map legend or key and tool tips, this is easy to accomplish, and the referenced documentation explains it well.

Step 7: Publishing Your Map With MapBox

After you’ve achieved the look the way you want for your map, you can export it to a number of different file formats.  If you need a high-resolution image for printing, you can export a PNG.  For an interactive web based map, you will export your layer as MBTiles. You cannot edit your map layer (colors, markers, marker size, tool tips or map key) after you export them, without exporting them again.  The MBTile file can be imported to your MapBox account to create a map that can be viewed on the MapBox website, or embedded into another website.  For our Toxic Algae Map, we used the “Easy Embed” option which creates an iframe that you can include in your website.


Learning how to use TileMill, and MapBox, and creating our map took about two days, though collecting and geocoding our dataset was an ongoing project throughout the summer.  The developers at MapBox were available to answer questions via their support forum and an IRC (Internet Relay Chat) Channel. The tutorials and documentation available for MapBox and TileMill is very straight forward and easy to follow.

As my colleague Penelope Whitney wrote recently, putting toxic algae on the map helped us tell a story that was previously difficult to express. It “connected the dots,” showing the breadth of the toxic algae problem, and the gaps in tracking it. What story will you put on the map?

Gregory Heller