The Insanely Illustrated Guide To Your First Data-Driven TileMill Map

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 and return to 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. 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.  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.

26 thoughts on “The Insanely Illustrated Guide To Your First Data-Driven TileMill Map”

  1. Great writeup! And keeping things insanely illustrated is really useful.

    One quick note – you can just click ‘Style’ if you don’t want the auto-generated style added to your project – ‘Save & Style’ is an entirely optional starting point.

    1. Hi, Tom!

      Hey, I just clicked through to your site and saw your project to put DC laws online. Wow, cool!

      You know, I did this so late last night, that when I just hit “Save,” I didn’t notice the styles I *did* have showing up. Maybe I need to hit “Save” in the editor window as well? Or maybe I was just tired and a little dopey 🙂

      I’ll add an extra note to the tutorial. For my collaborators who are absolute beginners, I often do stuff where we comment and uncomment code, just to see how things change. It’s a good way to get over “code fear” and get people into the “I can play with this” mindset. For a lot of the folks I teach, I want to get them to the point where they’re not necessarily writing code, but grabbing parts from the Global Junkyard of Code. For instance, I’d love for them to be able to grab other stuff to put in the “Style Editor” window…hmmm…maybe I’ll make a second Carto stylesheet…hmmm…

    1. Tell me how it goes. I’m happy to do a Google Hangout with the students, too. I love talking to students.

  2. Great tutorial. wonderfully illustrated! I didn’t know TillMill had a Google API script to help with geocode. That’s very helpful to know. will try it out soon. I wonder though, how about just using Goolge Fusion Table to auto-geocode (instead of importing/exporting data from Google Spreadsheet)?

  3. Great tutorial, but you lost me at “awesome plugin for Google Docs.”

    Please consider redoing this tutorial with non-proprietary tools. I can’t count the number of great projects my colleagues have started thanks to nice tutorials like this (which is good) focused around Fusion Tables (which is sort of good), only to have them break when Google inevitably changes something (which is very bad).

    Your work here is too good not to future-proof it! Maybe DSTK could be your geocoder?

    1. Patrick,

      You know, I have some of the same concerns about Google these days — who doesn’t? Your suggestion is a good one. I may not have time to come back to this tutorial very soon, but for those of you who are reading this: THERE’S MORE THAN ONE WAY TO GEOCODE ADDRESSES. In fact, there are about a zillion. I used the Google geocoding plugin because the people who created TileMill wrote it and recommended it in one of their own tutorials. I’m still enough of a beginner that I tend to use the first thing that works. Doesn’t mean it’s the best thing, as you so wisely point out.

      Lisa Williams, Data For Radicals

  4. Pingback: Map | Pearltrees

Leave a Reply

Your email address will not be published. Required fields are marked *