Satellite Background Map in Tableau - Part 2 - Adding County Lines

Version 1

    This document is a continuation of Creating a Tableau map with Satellite image background - Part 1. If you haven't been through that exercise, please do that first. Part 1 discusses the basics of setting up a Mapbox account, creating a style, uploading it, and using it in Tableau. I will not be repeating those steps and this part assumes you know how to do those tasks.


    Now it becomes important to understand some Mapbox Studio Classic terminology.

    • Sources. According to Mapbox documentation, “The source editor in Mapbox Studio Classic allows you to add one or more vector datasets or raster files and turn them into vector tile datasets or raster tile datasets, respectively.” Translation: "vector datasets" means shapefiles, among other things, and "raster files" means images. To you, this means you can add a shapefile and Mapbox will turn it into the format it needs.
    • Styles. According to Mapbox documentation, “The style editor allows you to write CartoCSS to style the map. This can be anything from changing the font labels to the color of the streets.” In Tableau terms, this is “formatting.” In Part 1, you used a predefined Style.


    Another term you will encounter shortly is "shapefile." A "shapefile" is actually a collection of files stored in the same directory. These files together include vector data including points, lines, polygons, labels and other attributes. It was developed by ESRI as an open standard for interoperability among GIS products.


    The satellite background map created in Part 1 lacks many features, including state or county borders, and the related labels. So, let's begin adding your own layer for county lines.


    Adding County Lines


    1. First, we need a source of the data. Fortunately, the US Census Bureau has already done that work for us. You can Google it like I did, but you will find lots of options that can be confusing. I'll make it easier for you: just click on TIGER/Line® Shapefiles. Here, you can find shapefiles for Counties, States, Congressional Districts, Census blocks, and much more. Select the data set you desire, and download and unzip it. I am using "Counties (and equivalent)" for this example. (I had trouble getting the file to download with Chrome, but it worked with I.E.)

    It is worth noting that there are a few different sources and links, even at the Census Bureau. One is at, which has simplified (i.e. lower resolution) versions. I prefer the more precise higher resolution versions at TIGER/Line® Shapefiles. However, any shapefile should work the same in this process.

    Up until now, you have been using a pre-built Style, and you haven't changed the styling in CartoCSS. You haven't done anything with Sources. Now it is time to create a Source, learn to add it to a style, and style it with CartoCSS. Take a breath and relax. It isn't as hard as it sounds.


    2. Go back to Mapbox Classic Studio. Click "Styles & Sources," then "New style or source."


    3. Then create a new blank source:


    4. Now that have a "clean slate," create a new layer:


    5. Select the .shp file you unzipped earlier, in this example: tl_2015_us_county.shp. You should now see boundaries of counties on a black background:


    6. Zoom it in a little bit, perhaps to level 4 or 5. See the zoom level here. z5 means zoom level 5:


    7. Enter a description for the layer, e.g. "county lines."


    8. If you select "Fields," you will see a list of data fields that are included in the "shapefile." Their meaning can be a bit cryptic. Here, you can provide a description for each field to help you, or others in your organization that might use this source, to use the fields effectively. (This is optional.)


    9. When satisfied, click Done.


    10. Select Settings. Set the Minzoom to 5 and Maxzoom to 10.

    The details of zoom levels are beyond the intent of this document. Briefly, the minimum zoom level is the level a which the layer begins to appear. The maximum zoom level is the maximum level at which tiles are rendered. If the user zooms beyond the maximum zoom level, this is called "over zooming" and it will be rendered, but without additional detail.

    11. Now, click Save As, giving it an appropriate name.


    12. Similar to the Style you uploaded in Part 1, you need to upload this Source to the Mapbox site, by clicking Settings->Upload to Mapbox. WARNING: this can take a LONG TIME! I believe my upload of the counties took 4 hours or more. Honestly, I lost track of the time, and I have done this multiple times. You can shorten the time by reducing the number of zoom levels even more than I suggested above.

    What it is doing in this process is converting the lines into "tiles," which are image file chunks for the entire space, for every zoom level specified.

    13. Once the upload is complete, you will have another Map ID which you will need in the next step. Copy it (by dragging across it with your mouse and press Ctrl-C).


    14. Now we need to create a new style based on one of the starter styles. This begins the same way we did in the first basic example. However, there is one problem in that first example: the "Streets - Satellite" style is locked, so you cannot add your custom source layer to it. To see this, click Layers:

    Fortunately, there is another option. This time, select "Satellite Afternoon," which isn't locked. Now, when you click Layers, you have the button "Change Source."


    I encountered some strange behavior when adding Sources. Several times, when I would add a Source to a Style, the layer would not appear in the layer list. When I would add a second Source, the layers for both the first and second Sources would suddenly appear in the layer list. At the time of this writing, I can no longer reproduce this behavior. I do not know what changed and therefore how to fix it. If you find that your layer is not available, you can try adding it a second time or adding another Source.


    I suspect this problem is related to a quirk. My experience has been that if you don't save the Style at each stage, when you try save it later with other changes, like layers, styles, etc., it will revert to the previous state and you have to apply all those changes again. I suspect that when I thought the layer wouldn't appear, it was because I hadn't saved it early enough in the process, so there actually wasn't any layer saved in that style.


    So, be sure to save it when told to. If you have a problem, restart at this point and try again. I will highlight these with "Save it!" Ctrl-S is the shortcut for Save.


    15. It is important that you save the new Style, giving it a name as you did before. Save it!


    16. To add your source layer on top of the satellite sources, click Layers, then Change Source, then in the text box next to the Apply button, at the end of the text, insert a comma, followed by the Map ID for the source that you copied earlier. Then click Apply.


    17. Save it!


    18. Now you can see your custom source in the red box below, and your new layer tag. Drag across it to select it, and copy it with Ctrl-C.


    19. To use this new layer tag, create a new style tab by clicking the + in the upper right corner:


    20. Give the new tab a name, like "counties."


    21. Click on the tab you just created.


    22. Now, it is time to begin learning CartoCSS. (Get started with CartoCSS | Mapbox is a good starting resource.) Each section begins with a "selector," which is the layer identifier, followed by braces surrounding one or more styling attributes. So, to show the county lines, create the CartoCSS code, pasting the layer tag you copied a moment ago into the new "counties" tab, and add the curly-braces to create an empty section:

    #tl_2015_us_county {




    23. Within the braces, you can add styling attributes as defined in the Docs. Click Docs to see various attributes that can be set. You will see they are grouped by the category or object type, like Map, Points, Lines, Polygons, etc. If you click on an attribute, it will expand to show the syntax and options for that attribute. For this example, we just want to expose the county border lines, so use "line-color", inserting it between the brackets, followed by a colon, space, and desired color:

    #tl_2015_us_county {

         line-color: red;



    24. Save it!


    25. Zoom in to a level in the range specified earlier when you created the Source, for example z5. Why? Because earlier we set the Source Minzoom level to 5. So, if the map is at a zoom level less than 5, the lines will not show. So, no matter what CartoCSS we create for this layer, we won't see the effect unless the zoom level is greater than or equal to the Minzoom of the layer. When you reach the previously set zoom level, the county lines should show with red lines.


    26. We can now publish this to Mapbox as we did in Part 1, and use it in Tableau. However, if you are using the free Starter plan, it won't let you because of the limitation of one Mapbox Studio Classic Style. So, you need to delete your first style from your account page in Mapbox. Select Classic, and click the trash can. You will be required to authenticate, similar to what you did when you created your account.


    You will also see that some other tools are available here, including your Map ID, same as you saw in Mapbox Studio Classic, stats, the ability to upload, etc.

    27. Now you can proceed with uploading your new style and using in Tableau.


    In Satellite Background Map in Tableau - Part 3 - Labels and Styling we will spruce this up a bit by adding labels for the counties, and adjusting some of the original CartoCSS.


    I hope you find this helpful. If you have questions about this document itself, like a step I missed or something that wasn't clear, feel free to post it here so I can improve the quality of the document. However, if you have general questions about Mapbox, or other things you are wanting to accomplish, please post them in the Forum, where others will see it and contribute.