Intro to Mapbox: Translating Geospatial Data Into Interactive Interfaces
In this tutorial we’re going to show you how to create your own custom mapping application in Mapbox. You’ll learn how to customize the look and feel of your map, upload your own data and visualize that data using Mapbox Studio and Mapbox GL JS.
Here’s the full example on Codepen: Contaminated Sites in Miami-Dade County.
This workshop was originally presented as part of the University of Miami’s Ribeiro Innovation Fund Workshop Series. Check out the full Zoom presentation below!
Why Mapbox?
First, let’s answer the obvious question: why Mapbox? Here at Seven Mile Media, we’ve used a lot of online mapping libraries over the years and Mapbox is by far our favorite. Mapbox comes with some amazing features out of the box including Mapbox Studio, which is still the most robust and intuitive basemap style editor we’ve used. And since it’s rendered using WebGL, Mapbox is always quick to load and buttery smooth, even when rendering 3D features.
Mapbox is free to start, but if you plan on publishing with it, you’ll likely need to pay some usage fees. Check out more about that on their pricing page. They have a generous free tier that allows you to get started quickly, but this is an important consideration if you plan on using it for a client.
Prepping the data
First, we’ll download the data. For this project, we’ll be visualizing a comprehensive list of all the environmentally contaminated sites in Miami, Florida from the Miami-Dade Open Data Hub. This dataset locates all the locations in Miami where environmental contamination has been documented in the soil or groundwater.
Next, we’ll upload the dataset to Mapbox Studio.
- Go to the datasets page and click New Dataset.
- Click the Upload tab and drop in the CSV file.
Once the file is finished uploading, open it in the Data Editor by clicking on it. This is a fantastic little feature of Mapbox Studio that allows you to edit points and polygons as well as adding and editing data attributes. For now, we’ll leave it alone and export the data to a tileset by clicking the Export button.
A tileset is a collection of raster or vector data broken up into a grid of square tiles, similar to the tiles Mapbox serves to display the basemap. This method greatly increases performance when rendering the data and allows us to create data-driven styling right in Mapbox Studio without touching a line of code!
Styling the map
Now that we’ve got our data locked and loaded, it’s time to style our map. Open up the Mapbox Styles page and click New Style.
Mapbox offers a selection of professionally-designed templates to choose from or you can create your own. We would highly recommend starting with a template that’s closest to the design you have in mind and customizing it from there. There’s a lot that goes into map design and it’s difficult to build one from scratch. The Monochrome theme is a good go-to starter for data visualization. Once you’ve chosen your template, click the Customize button.
The Style Editor gives you all the tools you need to customize the look of your map down to the tiniest detail. The Components tab lets you adjust view options by category. You can turn country and state boundaries on and off, tweak labels and even turn on 3D building models in the Buildings tab.
Now take a look below to edit the colors and typography.
- Change the colors on the map under the Color tab.
- Click Manage color palette for further customization.
- Change label styles under the Typography tab.
If you feel overwhelmed, go check out the Mapbox Style Gallery for inspiration. The possibilities are endless!
Styling your data
Once you’re happy with your basemap style, it’s time to style your data. Click on the Layers tab and hit the plus icon to add a new layer. Select the tileset you made from your uploaded data from the list below. You can change the type of visualization to fill, fill extrusion, line, circle, symbol, or heatmap. Since this dataset contains all point features, we’ll choose circle.
The Style tab allows you to change the appearance of your data by editing attributes like circle radius, color, opacity and stroke. You can choose to give these absolute values or you can use expressions, which opens up a range of options for data-driven styling.
Click on the Color tab and select Style with data conditions. This allows you to assign color variables to different data attributes, which is a great way for categorizing string data. For numerical data, you can also choose Style across data range, which allows you to map a range of values. Use this option if you want to create a choropleth map.
Colors can always be tricky when designing a map, especially when visualizing data by color. Check below the article for a list of helpful resources in choosing color palettes.
When you’re done styling, be sure to click Publish to make your map and data styles available to use in your web application.
Building the web application
We put together a handy little Mapbox Starter template to get you up and running!
Mapbox GL JS is an extremely powerful JavaScript library for building interactive maps from vector tiles and Mapbox styles, from online web maps to mobile applications. It has fantastic documentation which you can find here.
To get started, head to the Mapbox GL JS Quickstart guide and copy the code into your application. If you’ve downloaded our Mapbox Starter, this will already be in the code.
Include these JavaScript and CSS files in the <head> of your HTML file.
<script src=’https://api.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.js'></script>
<link href=’https://api.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.css' rel=’stylesheet’ />Include the following code in the <body> of your HTML file.
<div id=’map’></div>And include this code in your JavaScript.
mapboxgl.accessToken = ‘pk.eyJ1Ijoibmlja2hhcmIiLCJhIjoiY2pucnN4cWloMGJveTNxbjJ4dzg3dGM4eCJ9.YHcYBuehFvoDyGiJr6dBig’;var map = new mapboxgl.Map({
container: ‘map’,
style: ‘mapbox://styles/mapbox/streets-v11’, // stylesheet location
center: [-74.5, 40], // starting position [lng, lat]
zoom: 9 // starting zoom
});
Replace the access token with one of your own. You can create a new access token from this page.
Now replace the style URL with the URL from your custom map style. To find it, open your map in the Style Editor and click Share. You can copy your style URL here or download it.
Lastly, you’ll want to adjust the starting position and zoom level of the map. Replace the center and zoom attributes in your code, keeping in mind that center takes an array starting with longitude first, then latitude. If you need help finding your exact starting position on the map, try this handy location helper tool.
Now refresh your browser. Look, it’s your first data visualization map! 👍
Custom HTML popups
Now that we’ve got our basic map up and running, let’s add some interactivity. Take a look at this example which teaches you how to add popups when points or markers are clicked in a custom tileset.
Copy and paste the following code into your JavaScript, below the map initialization:
map.on(‘click’, function(e) {
var features = map.queryRenderedFeatures(e.point, {
layers: [‘layer-name-here’] // replace this with the name of the layer
});if (!features.length) {
return;
}var feature = features[0];var popup = new mapboxgl.Popup({ offset: [0, -15] })
.setLngLat(feature.geometry.coordinates)
.setHTML(‘<h3>’ + feature.properties.title + ‘</h3><p>’ + feature.properties.description + ‘</p>’)
.addTo(map);
});
Replace the layer name with the name of your data layer as it appears in the Layers panel of the Style Editor. Then replace the markup in .setHTML() with whatever you’d like your popup to display. Refer to your original data to find the exact names of your data attributes. You can also add console.log(feature) before the popup variable to see the data of individual points in the browser console by clicking on them.
Now refresh your browser and try clicking through your data. Look at all those contextual popups!
Adding a UI and flyovers
Finally, we’ll add some UI buttons and flyover events. Refer to this example on flying to a location.
In the <body> tag of your HTML, copy the following code below the map container:
<div id=”nav”>
<a id=”downtown-miami” href=”#downtown-miami”>Downtown Miami</a>
<a id=”south-beach” href=”#south-beach”>South Beach</a>
<a id=”mia” href=”#mia”>MIA</a>
</div>Copy the following code into your CSS:
#nav {
position: absolute;
padding: 30px;
background-color: #fff;
top: 40px;
left: 40px;
}#nav a {
padding: 0 15px;
}
Now copy this code into your JavaScript:
$(‘#downtown-miami’).click(function() {
map.flyTo({
center: [-80.193, 25.766],
zoom: 16,
pitch: 60,
bearing: 0,
duration: 6000,
curve: 2
});
});$(‘#south-beach’).click(function() {
map.flyTo({
center: [-80.134, 25.772],
zoom: 16,
pitch: 60,
bearing: 0,
duration: 6000,
curve: 2
});
});$(‘#mia’).click(function() {
map.flyTo({
center: [-80.286, 25.793],
zoom: 14,
pitch: 60,
bearing: 0,
duration: 6000,
curve: 2
});
});
Reload your browser and try clicking the different location buttons. Mapbox flies you gracefully down to each one to get a better view! This is a great feature for adding an extra layer of interactivity or narrative focus to your maps.
And that’s it folks! If you enjoyed this tutorial and have any questions or just want to say hi, leave a comment or reach out to us on Instagram. You can find maps we’ve built for clients and our other work on sevenmilemedia.com. Happy mapping!
Additional color resources:
