Simple web map using Mapbox-GL-JS
How to use Mapbox mapping API without a Mapbox key.
Edit to this post — As of Mapbox-GL-JS V2.0.0 Mapbox has changed their licensing structure, it will no longer be possible to use Mapbox mapping API without a token. See below for details on this change.
This post is designed to be a first start with using Mapbox-GL-JS web mapping library. In particular how to use Mapbox open software without needing a Mapbox token or using their tiles. Mapbox-GL-JS is an open JavaScript library, see more information. The library is under the 3-Cluause BSD Licence.
I was investigating different map technologies that I could use for both my own projects and for work. After googling, “can I use Mapbox-gl-js without having a Mapbox account or paying for tiles” it wasn’t apparent at first. There are a few posts and questions online, one question on Stack overflow and an issue on Mapbox GitHub page. However, I was struggling to find detailed posts on how to actually do it, hence this post. If you are new to web mapping or need a simple example to get you started, then read on!
Mapbox-GL-JS is a nicely rounded map library that is on the whole pretty simple to use. The creator of Leaflet (Vladmir Agafonkin), another great open mapping tool, works at Mapbox now and there appears to be many similarities between the two projects. To start with we are going to create a very simple map that uses Mapbox tiles, don’t worry we will go about swapping out the layers and removing the token later!
If you don’t already have a Mapbox token go over to https://www.mapbox.com/, create an account and grab a token. Our example will start with a Mapbox layer. The following example is from the Mapbox-GL-JS get started page and is a good place to start. Once we have a map we will build from there.
First off, we need to import the library itself and the CSS styling. Create an HTML file, let’s call it index.html.
If we open up our html file, we have our first map, pretty simple start.
We now have a basic map to start with using the Mapbox Streets layer tiles. First off, lets sort out the styling as our map is currently a small window. Let’s edit our style tag as provided by the Mapbox getting started example and separate the styling from the map div.
Re-fresh the page and you should now see the map cover the entire browser window.
A good start but let’s quickly add a start location and zoom level before replacing the tile layers and removing our token. This will be added to the map function we created earlier, there are a number of parameters that can be added to the map object allowing for different customization and control of the map. We are only going to add a start location, a zoom level and change the data layer to use our own tile service. First add the below centre point and zoom lines to our map object just beneath our style line.
Your map should now open over London.
Now we need to remove the Mapbox layers and add our own tile source. To add a new layer we need a source, layer, and style object. See here for much more detail on how Mapbox layers and styles work.
Within our style object we need to provide Mapbox with a source, and a layer object. Mapbox layers have been simplified to work from a simple key value style pair within the map object. Now we need to convert style into an object with a source and layer attributes. Use the below as an example.
In this case I am using a raster tile service from Stamen, who have created some interesting looking map styles. However, pretty much any raster or vector tile service ({z}/{x}/{y}), will work with Mapbox-GL-JS, it doesn’t have to be a vector service.
After copying the above lines into our html file, we should see something like the below;
Now that we have removed the Mapbox layer from our map and are using tiles from another source we can remove the Mapbox token line. That’s it. We have now created a simple map using the Mapbox-GL-JS library without having to include a Mapbox token or use any of their layers.
The final code:
Conclusions
It is pretty simple to separate the Mapbox-GL-JS api from the Mapbox tile sets and paid for services. Mapbox business model is based around data usage and providing a one stop shop for users mapping needs. However, most of their tools are Open Source, so people are free to use their code in their own projects. I am going to write a follow up to this post which will be how to use Mapbox-GL-JS within React.
