Fast and Fabulous Custom Maps Using Mapbox in Tableau

This guest post by Anya A'Hearn and Allan Walker was first featured on Datablick. Check out their site for more amazing #VizHacking

So the last time I wanted a custom map, I ended up building my own WMS and spending months and $’s to get the map I wanted. If you followed that advice – good for you. You and I can now drink at Tableau conference and tell the young’ins about how we used to have to walk uphill in the snow, wearing only flip flops and a Magnum BI t-shirt, while being pelted with popsicles to get our maps. Then one day recently, I had a cocktail with Allan Walker (that insane mapping Zen dude) who pointed out that if you just opened up a .tms file in notepad, there just wasn’t all that much to it but a wee bit of xml. Thank you again Allan.

Craig Bloodworth of The Information Lab and I spent some time investigating and customizing the Tableau “TMS” file. While I concentrated on delivering ESRI and Stamen basemaps, Craig took on Mapbox.

What follows is another DataBlick and Allan Walker and Craig Bloodworth bit of fun with maps.

Onto new, fast and fabulous. Seriously, this is gonna rock your Tableau map world. Go to and scroll down to the Mabox Studio section.

go to map

Download and open Mapbox Studio. Once open, click on Start a New Project.

Click to start a new project

You will be able to select from a bunch of great vector types with different map styles to use as the base layer for your map. You could also start from scratch, but this is all about getting to fabulous fast! For this tutorial, I a going to pick “high contrast”, but feel free to select whatever you like.

Pick from some amazing vector tile base maps

Once you have selected the base you can use the looking glass to search for a city or area that may be of interest by typing it in the search box. I of course will be using my favorite city, San Francisco.

Zoom into SF on Mapbox

Now notice all of the lines of “css – like” code to the right of the map view? At this point Allan of course says, “make it black”. Because as you all may know, every map he makes is all “Johnny Cash” black…


Now before going any further, make yourself a snack and open a bottle of wine, because this is where the fun begins. You may very well find yourself sucked into playing with your new map super powers for hours. Click on a little circle that has color in it. Pick a good one, like water or land. Go on, make them hot pink. Now hit the save button in the upper left corner of the screen. Notice the map updates right away. You can also just enter a hex code for the colors if you need an exact match. Play, play play!

I of course am going to use the colors from my SF Giants, and got the exact colors from a fun site called

pick you favorite team hex colors

You can change fonts, colors, line opacity, thickness, etc. and also do it for different levels of zooming in and out. One helpful hint is to copy all the code and paste it in TextEdit so you have a backup in case you mess up. You can also type ”//” at the beginning of a line to comment things out and test what it looks like before you delete them.

So by now a few hours have probably gone by and you have something fun like my SF Giants map style.

Mapbox styles like SF Giants

Time to upload your work of art so that you can use it in Tableau. Click on the Setting button on the upper left corner, and then Upload to Mapbox. After you click on Upload you will notice that right above where you clicked there is now a Map ID. This will have your username, plus a bunch of letters and numbers after it. Copy and paste that in a TextEdit file for use in a minute. Click on that MapID and you should be taken to

click to upload your new style to map box

Notice the API Access token at the top. Copy and paste that into the same TextEdit as your Map ID.


Now open up the sample.tms file below, and copy and paste it into a TextEdit file.


Using copy and paste, put your access token in place of the one in the .tms file (red box).

change access token

Also give your map a fun name in the two map display name areas so you recognize it in Tableau.

display name

Then use “Find and Replace” to update all the Map ID’s to use yours.

replace map id's

If you are planning on publishing to Tableau Public or server, change the “false” to “true”


Lastly, if you are feeling extra naughty (as you have had that bottle of wine by now, right?) put something clever in the map-attribution text section.

change attribution

Save your .tms file with a new name. This will be the name that you will see in Tableau so make it descriptive. Place this file in your c:\Documents\MyTableau Repository\Mapsources folder.

add to your map sources folder

You will have to restart Tableau. After it restarts, open a workbook that had some Geo fields in it, like SuperStore and create a sheet with that data on it. Go up to the Map menu, and then select Background Maps. You should see the new .tms you just made. You totally made a Giants one too right?

select your new tms file

Wait? Where’s my awesome map? To see it, you have to select the Map menu again, and then select Map Options. Then select the Map Layer with your map’s name.

click to show your map layer

There it is! Your own custom background map .tms in Tableau.

your tms in Tableau

Zoom in, pan around. Enjoy! You now know where the folks that shop at SuperStore live, and that they are Giants Fans!

zoom in and pan on your map

Stay tuned for the next post…. map layers you can turn on and off at will. Maybe get a case of beer for playing with that one.

Subscribe to our blog