Mapbox map API

by Cédric Aellen /

Maps are cool and I love them. Since I’m rebuilding this blog, I wanted to add some of them in the design. As I love trekking, I was thinking it was a fine idea to add them on posts where I talk about trekking and things like that. Katy DeCorah was already doing that on her blog. Her work was a great inspiration.

I will show you how I build this for this blog based on Jekyll.

Mapbox provide an API to build static maps. This is what I use to add the maps as background image in the header. I use static maps because they are only used as design elements. They don’t need to be zoomable, etc.

Building a map

The request

This is the request for a map:{mapid}/{lon},{lat},{z}/{width}x{height}.{format}?access_token=<your access token>

What do we need ?

Here are the things we need:

Things that don’t change

The mapid and the access_token will always be the same. So I put them in the _config.yml config file. If they change, I just need to update them in one file.

mapbox_token: ...
mapbox_mapid: ...

height and width are hardcoded in the request. It would be nice to put them too in the config file. But I’m looking to add some media queries. So at this time, I keep them here.

The format will be .png because PNG is cool. It is hardcoded too.

Specific value

The only value that will change from a post to an other are the coordinates where to center the map and the zoom factor.

We will add them in the Front Matter of the post like this:

coordinates: 6.407948,46.718826
zoom: 13

Build the request

We have to build the request for the background image.,46.66,11/800x800.png?access_token=pk.eyJ1IjoiYWxpZW5sZWJhcmdlIiwiYSI6Ik1hN3ZxVjgifQ.S2hbxqNnn7kU7HRnd6jYVg)

As you can see, the page.zoom isn’t required. If there is no zoomvalue in the Front Mater, it will be set to 15.

The result

And here is the result:,46.718826,15/800x800.png?access_token=pk.eyJ1IjoiYWxpZW5sZWJhcmdlIiwiYSI6Ik1hN3ZxVjgifQ.S2hbxqNnn7kU7HRnd6jYVg
Map of the Saut du Day
The map generated by the request

We want markers !

Maps are cool but if we can add marker, it’s even cooler. And yeah (!), we can do that with Mapbox

We have to add the markers in the request juste after the mapid.{mapid}/{markers}/{lon},{lat},{z}/{width}x{height}.{format}?access_token=

Markers parameters

The {markers} have to be formatted like that:


As everything are is specific for each post/map, we will add this in the Front Matter of the post.

- coordinates: 6.407948,46.718826
  name: pin-m
  label: water
- coordinates: 6.400716,46.717375
  name: pin-m
  label: rail
- coordinates: 6.400437,46.716507
  label: parking
- coordinates: 6.395974,46.722333

Build it

Here is the liquid template code for the markers:

{% for marker in page.markers %}
  {% if %}
    {{ }}
  {% else %}
  {% endif %}
  {% if marker.label %}
    -{{ marker.label }}
  {% endif %}
    {% for coordinate in marker.coordinates limit:1 %}
      {{ coordinate }}
    {% endfor %}
  {% if forloop.last %}
  {% else %}
  {% endif %}
{% endfor %}

As you can see, name and label are not required.

So now, let’s put everything together.,46.68),pin-m-m(6.52,46.67),pin-m-m(6.52,46.66),pin-m-m(6.52,46.65),pin-m-m(6.52,46.64),pin-m-m(6.53,46.67),pin-m-m(6.54,46.66),pin-m-m(6.55,46.67),pin-m-m(6.56,46.68),pin-m-m(6.56,46.67),pin-m-m(6.56,46.66),pin-m-m(6.56,46.65),pin-m-m(6.56,46.64),pin-m-a(6.58,46.66),pin-m-a(6.58,46.65),pin-m-a(6.58,46.64),pin-m-a(6.59,46.67),pin-m-a(6.59,46.65),pin-m-a(6.60,46.68),pin-m-a(6.60,46.65),pin-m-a(6.61,46.67),pin-m-a(6.61,46.65),pin-m-a(6.62,46.66),pin-m-a(6.62,46.65),pin-m-a(6.62,46.64),pin-m-p(6.64,46.68),pin-m-p(6.64,46.67),pin-m-p(6.64,46.66),pin-m-p(6.64,46.65),pin-m-p(6.64,46.64),pin-m-p(6.65,46.68),pin-m-p(6.65,46.66),pin-m-p(6.66,46.68),pin-m-p(6.66,46.66),pin-m-p(6.67,46.68),pin-m-p(6.67,46.66),pin-m-p(6.68,46.67)/6.6,46.66,11/800x800.png?access_token=pk.eyJ1IjoiYWxpZW5sZWJhcmdlIiwiYSI6Ik1hN3ZxVjgifQ.S2hbxqNnn7kU7HRnd6jYVg
Map of the Saut du Day with markers
The map with some markers

Let the fun begin

I hope you will have as much fun as me.

Map with some fun marker placement


This is how I place those maps in the design.

See the Pen Full height image header by Cédric Aellen (@alienlebarge) on CodePen.