The INN Guide to Creating A Data Driven Map With TileMill

TileMill is a free-to-download application for Windows and the Mac that will let you build beautiful, data driven maps.  If the bland sameness of Google maps is giving you ennui, TileMill might be a good alternative for you.   There are many beautiful stylesheets to make TileMill maps visually distinct, and you can control the colors, line widths, and much more about your map using Carto, a CSS-derived language.  Here's a beautiful map of Montreal using a watercolor-like stylesheet:


What follows is a detailed, highly-illustrated guide to creating your first map in TileMill.  We will be using real data from the Rhode Island Data Hub, a catalog of public data about education, employment, health, and much more from Rhode Island.

First, download and install TileMill.

Remember:  you must click many of the images below to see them full size -- you'll need to do that for many of these images.

Without a dataset to play with, our map will be pretty boring.  So our first step is to acquire, clean up, and enhance some data.  I never use fake "example" data in my tutorials -- we always use the Real Stuff around here.  So our map is going to use early education data from Rhode Island that you'll grab and mess with yourself.

Step 1: Visit RI Data Hub And Browse The Data Catalog


Go to and click Data Catalog.

Step 2:  Grab Your Data


In the "Text Search" box, type "early intervention" (no quote marks).  Click on the first link, # Children <3 Enrolled In Early Intervention.  Note that there are two files: one is the number of children in early childhood intervention programs, one is the percent.  You want the one with the number.

Step 3: Download Your .CSV


{PSST!  Here's a downloadable .CSV if that doesn't work for you! -- D4R  KIDS-IN-EI-BEFORE}

You'll get a pop-up window for a .CSV (comma separated value) file.  Click on that to download.  Remember where you save it!

Step 4: Create A New Google Spreadsheet


Go to Google Docs/Drive and create a new spreadsheet.

Step 5:  Import Your .CSV into Google Docs


Click File > Import and import your new CSV file.

Step 6:  Clean Up Your Data


Change the name of your spreadsheet to something descriptive that you'll remember and delete Column A, which we won't need.

Step 7: Start a New TileMill Project


Open TileMill and click "New Project."

Step 8:  Add Your Project Metadata


Describe your project.  Remember to note where your data came from in case you need to refer to it later!  Click "Add" when you're done.

Step 9: Check Out The Tile Mill Interface


This is what the TileMill interface looks like: a map on one side, your style editor on the other.  You'll start out witha  blank map.

Step 10: Geocode Your Data

There's one problem that we have to deal with with our data:  it has city names, but it does not have latitude and longitude data.  TileMill does not have built in "geocoding" (geocoding is the process of taking plain-language names, like "Snowflake, Arizona," and turning them into a set of latitude and longitude coordinates like "34.5133° N, 110.0778° W" which a program like Tile Mill uses to drop points onto our map).

The good news is that TileMill has created a nifty plugin for Google Docs spreadsheets that will geocode our data for us.

In Google Docs, while looking at your uploaded spreadsheet, click Tools > Script Editor.


You are going to copy and paste TileMill's geocoding script into the next window, so go to this link and copy the entire thing:  Geo For Google Docs.  It looks like this:


Cut and paste the code into this window.  Change "Untitled project" to "Geo." When you are done, click the "save" icon (the one that looks like a floppy disk -- how retro!) and return to your spreadsheet.


Refresh your spreadsheet.  You'll notice you have a new menu item next to "Help."


Next, select the column of data you want to geocode.  Select the whole column, including the title.  Then click Geo > Geocode Addresses.


Google Docs may ask your permission to run the script the first time you do this.

You'll see this window.  Mapquest doesn't require an API key, so use that one and click "Geocode."


You'll get three fresh columns of data -- pretty nifty!



Step 11:  Download Your Geocoded Data From Google Docs And Add It As A Layer To Your TileMill Map

Download your spreadsheet as a CSV.  Also, shorten the Kids In EI column name to KidsInEI.  It's good to make column names short, memorable, and without spaces.  If you haven't, rename the .CSV file to RI-KIDS.csv. Tile_Mill_19_B

We'll be using this as a "layer" in our otherwise blank map.


Select your .csv file and add it as a layer.

When you do this, it will ask you what you want to select as the Carto ID.  In that text field, put RI-KIDS (the name of your spreadsheet).  Hit "Save."

You still won't see anything on your map, because we haven't told StyleMill what we want to do with that data.  Let's do that now.

Step 12: Style Your Data

Select the following code and paste it into the style window (to the right of the map):

Hit "Save" at the top of the editor window.  You might have to zoom around a bit to find Rhode Island if TileMill doesn't autozoom, but your map should now look like the picture below.  Remember that you can click on any image in this tutorial to see it fullsize, so do that if you can't read the word-bubbles.


So now we have some nifty dots, but they look a little weird hanging out there in space when there are no state borders on our map.  Let's upload a new layer to draw the state borders on our map.

We'll be using something called a shapefile (.shp) to do this.  Shapefiles can describe the shape of a country, city, town, legislative district -- you name it!   You can download the shapefile we will be using here: 50 States Basic Shapefile

Click Add Layer again.


Once you've added your states.shp file, click "Done."


On the next screen, click "Save & Style."


Wow!  That looks terrible, doesn't it?  That's because TileMill autogenerated some default style code and put it in the Style Editor window.


You'll find this code at the end of all the code in the Style Editor window.  Delete it, and click "Save" at the top of the Style Editor window.


Now your map will look like this.  Much nicer!

In truth, we could have just clicked "Save" during the last step and skipped turning our map green -- but it's actually pretty good for us to get used to the idea that we can cut and paste segments of code in our Style Editor window.  You want to build your comfort level messing with the code itself!  

Notice that we now have the borders of states drawn in.   We actually already had style data for #states in our code.  Can you change the line width for the state borders?  How about the color?  Remember, you won't see any changes to your map until you hit "Save."

Now's a good time to zoom out and see if any of your dots are in the wrong place.  If they are, you can look up their lat/lon coordinates manually by just typing "Placename lat/lon" into Google and adjusting them manually.  Geocoding scripts do make mistakes!

How about making some tooltips?  Tooltips are little windows that pop up when you roll a mouse over one of the dots on your map.  Go to the lower left where the "layers" button is and you'll see a button that looks like a hand with the index finger pointing up.  Click that.   At the bottom of the window that pops up, use the pull-down menu to select the spreadsheet you uploaded.  In the text window below, you'll see the name of each column in between three curly braces (curly braces look like this: { } ).


Click on the "Teaser" tab at the top of this pop-up window.  You can use regular ol' text or HTML to write your tooltips.  But you don't write one for each data point.  Instead, you use the name of the column where you want that data to appear.  Check the example below:


When you make changes here, remember they won't take effect until you hit the "Save" button above the Style Editor window.  Close this pop up button and run your mouse over the dots.  Now they should have little tooltips that pop up and say  things like "Woonsocket has 800 kids in Early Intervention programs".

Let's make a legend, too, to tell viewers of our map what they're looking at.


Remember to click "Save" above the style editor window when you're done!

Now that you've got a map, you can upload it by clicking "Export."  The easiest way to share your map is via the free MapBox service, created by the same people who make TileMill.  You can upload your maps there.  Once they're up there, you'll be able to embed them in any site the same way you do a YouTube video.

Here's what our map looks like, once we've uploaded it to MapBox and embedded it here.