What is Mapbox GL JS? (And How To Use It)

As someone who both loves maps and visualizing data, I was very excited when I found Mapbox GL JS. GL (standing for Graphics Library) and JS (unsurprisingly standing for JavaScript) is a JavaScript library that allows you to create maps that can include interactive data. GL has its roots tied to WebGL, an API that can render both 2D and 3D graphics that yield some fascinating results (see here).

Before using this API however I wanted to see how my rendered data would first look like on a map. For that I utilized Mapbox Studio which can be best described as Photoshop for mapmakers. Similar to Photoshop in the sense that it contains layers that can be easily manipulated, MapBox contains layers that consist of map styles, datasets, or tilesets. Tilesets refer to a collection of raster or vector data while datasets are an editable collection of GeoJSON features. GeoJSON can represent space (a Geometry), a spatially bounded entity (a Feature), or a list of Features. Essentially, it is a JSON file that refers only to geographic information.

When uploading data to Mapbox Studio however CSV (comma separated values), GeoJSON, MBTiles, KML (keyhole markup language), GPX (GPS Exchange Format), Shapefiles, and GeoTIFF (Tagged Image File Format) files are all accepted data file types. But when using Mapbox GL JS, I have found GeoJSON files to be easier to use.

The next stop was finding the data. Because my interests extend also to environmental science, I decided I would like to find animal migration data. For that I used Movebank, a useful online database of animal tracking data provided by the Max Planck Institute for Ornithology.

Though there is plenty of data that you are allowed to see rendered on their website, you have to be very specific in your search to find data that you can download. To quickly narrow down what data is available for download click on the i (information) icon next to any study and select “Open in studies page”. Once there go to the drop down and select “Studies where I can download any data” as shown below.

Once you find data you would like to use simply click the Download tab above the study page and you will be given several options as to what file type you want (if using in Mapbox you’ll want to select CSV format). Since some datasets are exceptionally large and can sometimes slow down the rendering of the data on the map, selecting “Filter by date” is a helpful work around. Because the bald eagle data I used was very large (GPS locations and timestamps taken every two hours for several years add up!) I opted to just use the data recorded in one month.

*side note: If you are looking to use data from Movebank, make sure to change the columns that say “location-long” and “location-lat” to instead be “longitude” and “latitude” or else Mapbox cannot properly interpret the data.

Once logged into Mapbox Studio simply create a new “style” a.k.a. map and proceed to add a tileset for the data you just downloaded. When you have your map open in the editor go to the top of the left hand bar and click “Add Layer”. Here you can select from tilesets that you have already downloaded or add a new one. Once you have added your tileset as a layer you should see it rendered on the map. For a more detailed step by step guide on this, see here.

Now onto the fun part! Here we’ll find out where bald eagles traveled throughout British Colombia in July 2018 with Mapbox GL JS. At the end, our data should look something like this:

For simplicity purposes, I’ve made the data available for download in GeoJSON format here. It can be added as another file in the same location as your index.html.

Before creating any files, first make sure you are signed up and have your own access token and that you have a text editor that can write in HTML, CSS, and Javascript. Once you have that, feel free to use this starter code in your index.html file.

This will render the map but we will not have any data on it yet. To add data we will need to add

map.on('load', () => {
   map.addLayer({
     id: 'eagles',
     type: 'circle',
     source: {
     type: 'geojson',
     data: './baldEagles.geojson'
   },
   paint: {
     'circle-radius': 5,
     'circle-color': '#6c0284'
    }
   })
  })
 })
})

then run it on our local server by running

python -m SimpleHTTPServer 8000

(you can pick whichever port number you like)

And that’s it! If you want to be more particular with the display of your data, within the addLayer method you can further customize your data. For instance, if I want to show the location of only one bald eagle at a particular time and place I can simply add

filter: ['==', ['string', ['get', 'timestamp']], '2018-07-06 00:01:00.000']

after the paint property. Mapbox also provides some very extensive documentation on further styling.

Very often finding the data you want to use and having it in the right format can be the most time consuming. But with Movebank and files in the correct format, rendering you data in the Mapbox GL JS API is a breeze.

Also, a very special shout out to the Bald Eagle Tracking Alliance for making this data available to the public!