GEOG 865
Cloud and Server GIS

Creating a custom basemap with Mapbox


As you saw with ArcGIS Server, online base maps can have dozens of layers, with all kinds of rules about what zoom levels they are hidden and displayed; therefore, we’re not going to start from scratch. Instead, we’ll start with existing Mapbox basemaps (which are pretty well designed to begin with) and make small modifications to fit our taste.

First, please download the data for these lesson 5 exercises. After you download the data, unzip it.

We’ll start out simple by infusing some of our own data into one of the Mapbox basemaps. We’ll then view our creation in ArcMap, where you already know how to add more layers on top.

Suppose you’re examining nighttime safety in the Washington DC area. You want to understand where activities are occurring at night relative to existing street lighting. The “Dark” basemap offered by Mapbox looks appealing for your purposes, but you want to integrate a layer showing areas that are illuminated. You plan on eventually doing some visualization of street vendor activity, pedestrian patterns, crimes, and other happenings in relation to the street lighting.

For the best user experience, you should complete the following steps on a desktop computer (not a tablet or phone):

  1. Open a web browser to, click Products > Mapbox Studio and click Get Started.
  2. If you haven't done so, make up a username, e-mail address, and password and click Get Started.
  3. Click Design a map style. This takes you into Mapbox Studio. Following the model of most software as a service offerings, this tool runs directly within the web browser (previously you had to install a tool on your desktop). It allows you to choose colors, text, and symbol weights to be used in a basemap. The base data is from OpenStreetMap, although you can also load in your own layers.
  4. On the left side of Mapbox Studio, click Styles and click the New Style button.
  5. Name the style StreetLighting, select the Dark basemap, and click Create.
  6. Zoom your map into the central area of Washington DC.

    This map looks great, but wouldn’t it be nice if we could add the areas illuminated by street lights in a soft yellow glow? Let’s do that. First, we’ll need to upload our data.
  7. On the left side of Mapbox Studio, click the Tilesets icon, which looks like four little diamonds.

    Tilesets are the vector tiles that Mapbox uses to encapsulate data displayed on the web. They’re very different from the rasterized tiles you worked with in ArcGIS Server. You can upload a vector dataset like a shapefile, and Mapbox will turn it into vector tiles, which it then hosts on its servers. You don’t ever really work with the tiles directly, but you can define styling rules to dictate how they should look. These styling rules can be changed on the fly because they are not “burned into” the tiles as they are with rasterized tiles.
  8. Click New Tileset and upload the shapefile included in this lesson. I derived this from a dataset of street light locations and wattage that I obtained from the Open Data DC website. The lighted areas are just variable distance buffers based on a very unscientific mathematical formula (ie., I made it up) based on the wattage of the light.
  9. If necessary click the Tilesets icon on the left side of the Mapbox site and click your light-areas tileset.
  10. Click the Add to Style button and then choose your StreetLighting basemap. This will launch you into the style editor window, showing you the new parameters of the layer you’re about to add.
  11. Look over the new layer properties (but don’t change any) and click the Create layer button.
  12. In the layer list on the left hand side, drag and drop your light-areas layer so that it is underneath all labels and boundaries. To drag the layer, you’ll need to grab it on the right side of the box, as shown below.
    Changing the layer order in Mapbox Studio
    Figure 5.1: Changing the layer order in Mapbox Studio
  13. Click your light-areas layer and modify its color to a bright yellow with an opacity as 0.5 and no antialiasing as shown in the image below. This gives the street lights a soft glow.
    Symbolizing street lights in Mapbox Studio
    Figure 5.2: Symbolizing street lights in Mapbox Studio
  14. In the upper left of your screen, click the Publish button and confirm you want to do this by clicking Publish again (not Publish as new).
  15. On the left side of the screen, click the Styles button (paint can), then click your StreetLighting style and click Share, Develop, and Use (in the right-hand list).
  16. Scroll down to the heading Mapbox WMTS Service and copy the WMTS endpoint.
    ArcMap is more wired to connect to servers rather than individual layers. This becomes an issue with tiled datasets, which are usually just hosted on a web endpoint with no need to do any special communication with a server. One way around this is to use a WMTS (web map tile service) which is an open specification for serving map data over the web via tiles. ArcMap has a user interface for making connections to WMTS services.
  17. Open ArcMap (on your own computer or on your EC2 instance, if you have licensed it).
  18. In the Catalog window, find the GIS Servers item and click Add WMTS Server.
  19. In the URL box, paste the WMTS endpoint that you copied from the Mapbox site.
  20. Click OK. It’s going to ask you for a name and password, but just click Cancel as many times as you need to in order to dismiss those messages.
  21. In the Catalog tree, you should now see an item called Mapbox on It might have a little red x on it. That means it’s not connected. Double-click the item to make a connection.
  22. Expand your connection to Mapbox on and find your StreetLighting layer. Drag and drop it into the ArcMap table of contents.
  23. Zoom in to Washington DC. As you get close, you should see your street lights layer appear.
    Hooray! You now have your Mapbox map as a basemap in ArcMap. Now you could do other kinds of visualization and analysis on top of that layer.
  24. Just for fun, add your sidewalk_vendors.shp shapefile (included with this lesson’s data) as a layer in ArcMap. I also obtained this from It contains the locations of registered street vendors in Washington DC.
  25. Style and label the street vendors in such a way that you can get an idea of which ones are surrounded by lots of lighting and which ones are in the darker areas.

To recap, you took an existing Mapbox-designed basemap and fused in some of your own data. You then brought this into ArcMap so you could work with it as a basemap. The next walkthrough will go beyond this, showing you how to modify the Mapbox design, create your own thematic data, and view your creations on the web.