[UPDATED! This tutorial is newly updated as of 1/28/17 with new geocoding instructions and now works again!] 

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.

TileMill Workaround: Having problems installing TileMill on newer Macs? Find that it hangs when you first open it? 


There is a workaround. Go to the TileMill menu, and click “Updates Preferences.”  You’ll see a dialog box like this: 


Click on “Install Developer Builds” and then click Check Now/Check for Updates. Tilemill will download a version with a patch. When it asks to relaunch, say yes. This should get you going again.

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 RIDataHub.org and click Data Catalog. [NOTE: Since this tutorial was written, you now need to create an account on the RI Data Hub to download data. If you don’t feel like doing that, feel free to scroll down and grab the ready-to-go .CSV file of this data].

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. You will need a free Google Drive account for this step, if you don’t have one already.

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 there are several free add-ons for Google Docs that will translate our place names into latitude and longitude coordinates for us. We’ll be using Geocode Cells.  First, you’ll want to get the add on, like this:


Geocode Cells will need your permission to run. Click “Continue,” and on the next screen click “Allow.”


You may find that Geocode Cells opens a blank Google Sheets spreadsheet for you. Copy and paste your data into it — you’ll notice that spreadsheets in other tabs won’t have the newly added geocoding option. Once you’ve copied and pasted your data, select the cells that you want to geocode — in this case, the city-state pairs.


Once you have your cells selected, click Add-ons > Geocode Cells > Geocode Selected Cells.


Geocode Cells will ask you if you want it to create columns for the latitude and longitude data. Click yes.


You’ll get two fresh columns of data — pretty nifty!


Before you leave, name your sheet “kidsri” and make sure column B reads “KIDS_EI.”


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 TileMill what we want to do with that data.  Let’s do that now.

Step 12: Style Your Data

Select the following code. You’ll notice at the bottom of this little segment of embedded code you’ll see a link that says “view raw.” Click on that and you will see this code in a new tab. Copy and paste the code into into Tile Mill’s style window (to the right of the map). You’ll already see a little code there — just get rid of it and replace it with the code below. 


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.


As you add layers, remember that Tilemill is looking for two things: 1: the name of your spreadsheet, and 2: the name of the column with the number of kids in Early Intervention programs. Look at the screenshot above. #rikidsineisheet1 is the name of the google spreadsheet, with a # in front of it. #KidsInEI is the name of the column with the data on the numbers of kids in EI programs in each town. If what’s in the style window (the window with the code to the right of the map) doesn’t match the spreadsheet you uploaded as a layer, nothing will show up on your map. To make sure they match, click the “layers” button in the bottom left of the TileMill window. The names of the layers have to match what you have in the style window. Don’t try to change the names of your layers — just make what’s in the style window match what your layer names are. This is a good reason to keep the names of .CSV files and columns you will use short and don’t use spaces — you may have to type them and they do have to match.

Remember, whenever you make changes in the style window or upload a new layer, you have to hit “Save” right above the style window. Until you save it, you won’t see any changes on your map.

Once you’ve done that, you should see dots start to appear on your screen. 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.

27 thoughts on “The Absurdly 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. lisawilliams says:

      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…

  2. Mirko Lorenz says:

    Thanks for this guide, much appreciated.

    1. lisawilliams says:

      It’s my pleasure! Your project looks very interesting!

  3. Awesome tutorial, Lisa. Very, very helpful. Can’t wait to try it out in the fall in a new multimedia reporting class I’m developing!

    1. lisawilliams says:

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

  4. I too had written about Tilemill visualizations couple of months back. Here’s a link to the short tutorial I wrote. I mention the alternate method to geocode your data which is search for ‘Geo’ under Script Gallery and install ‘Geo’ by dhcole@gmail.com.

  5. Cheri says:

    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)?

  6. Patrick says:

    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. lisawilliams says:


      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

  7. angel says:

    Hi Lisa..great tutorial…only a question..how add the states names to my map??..thanks!!!…..

  8. Pingback: Map | Pearltrees

Leave a Reply to lisawilliams Cancel reply

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