DEV Community


Using the Mapbox GL API to add maps to your next project

Elijah Merrell
I'm a UI software engineer at Pulse Secure.
・4 min read

A map is a powerful tool that can be used to convey geographic information on your next web application. There are many options in the developer's toolbox when choosing a mapping API, but Mapbox is by far my favorite. I come from a geographic information science background (GIS) and have spent countless hours tweaking map designs in Adobe Illustrator. Adobe gives users tons of freedom when it comes to tweaking map colors, labels, and fonts, but most mapping API's lack this functionality. This is where Mapbox is different. Mapbox provides the developer with a seemingly endless number of options when it comes to customizing the design and functionality of maps. From adjusting base layers to selecting a custom color palette, there are many ways to design the perfect maps for your needs.

So how does Mapbox do it? The answer is that Mapbox is (mostly) built on data from Open Street Map, the open source mapping project where volunteers contribute to a public repository of geographic data. Mapbox takes this data and transforms it into layers. Each layer is a visual representation of its source data, and the style of each layer can be adjusted by editing a JSON document that contains the style for the map. The JSON file can be used to fine-tune the look of your maps.

A quick Mapbox tutorial

By this point, you probably get the point of my post: I think Mapbox is awesome. It has a lot of great features and the sky is the limit in terms of what you can do with the Mapbox API. But how do you actually use it? It turns out that with a few simple lines of HTML, CSS and JavaScript, you can have a map on your page in no time.

Initial Setup

The first step in getting Mapbox up and running is to setup a developer account. Mapbox allows you 50,000 map views per month without needing to pay (nice!). Once you have reached 50,000 views in a month, it costs $0.50 per 1,000 additional views. Once you have setup an account, Mapbox will provide you with an access token that you'll use to access the API. Mapbox gives you a few options to get a map up and running. The first is using the Mapbox content delivery network (CDN), while the second is using NPM to bundle modules. For the sake of this tutorial, I'll be using the CDN method.

Getting a map on the page

To use the Mapbox CDN, you simply paste the following two lines of code into the head of your html document:

Once you have this code in the correct spot, you can initialize a new map with a few easy steps. The first is to create a div that will house your map and give it a unique id. For this example, I called the div 'map-container'. Once your div is setup, you will need to write a few lines of JavaScript to create a new map. You can do this either in a separate .js file or within a script tag in your html document. To initialize a new map, set a variable and assign it a new instance of the Mapbox GL map class. Note that you will also need your Mapbox access token within this script:

Now that your code is in place, you can open up the html page in your browser and there should be a map! You can now interact with the map on the page by panning and zooming. Here is the map that we initialized with the code from above. At this point, it's a zoomed-out map of the world that isn't really conveying any interesting information. Let's make a few changes and get it to display something a bit more intriguing.

Map customization

We have successfully gotten a map to display on our page. Let's make a few adjustments to get it displaying something a bit more interesting. For this example, let's have our map show the location of the Flatiron School in Seattle. I was able to get the coordinates for Flatiron's location using a free online geocoder that accepts an address and returns latitude and longitude coordinates. We can add the coordinates to map and adjust the zoom level to reflect the location on the page.

To center the map on Flatiron's location, I set a variable 'flatiron' equal to an array of the coordinates in the form of [longitude,latitude] using decimal degrees. I then set the 'center' property of the map to use this variable, and set a zoom property to a zoom level of 15. I then created both a popup variable and a marker variable and set these variables to instances of the Mapbox Popup and Marker classes that again used the flatiron coordinates variable.

To put the finishing touches on the map, I linked a css stylesheet to the html page and styled the map marker using a few lines of css. I was able to use Flatiron School's logo as the marker and enable a popup window when the marker is clicked. You can use the popup window to display any information you'd like. In this case, I added a title and a quick blurb. That wasn't so bad was it? Our finished product was easy to create and highlights the easy customization and setup provided by the Mapbox GL API. Now let's sit back and admire our work:

This tutorial really just scratches the surface of Mapbox's capabilities. I highly recommend checking out their documentation to see all that is possible with this technology. The following link will take you to the Mapbox GL API docs: Now get out there and start making some maps!

Discussion (0)