
Mapbox is one of the nicest way to embed custom dynamic maps in an app as there are lots of customisation options. I'm using their service on my route exploration website [Trail Router](https://routes.kevchentw.com) to display running & hiking routes from gpx files. In this post I'll go over how I used Mapbox's [static image api](https://docs.mapbox.com/help/glossary/static-images-api/) and [Node Canvas](https://github.com/Automattic/node-canvas) to create custom og sharing images like the example below:

<Image
  alt="Nyckelviken Trail Route"
  caption="Custom Open Graph Image for Nyckelviken Trail Route"
  src={'/blog/mapbox-static-image-api/nyckelviken.png'}
  width={1012}
  height={516}
/>

The code used looks like this:
```jsx
const fs = require('fs')
const path = require('path')
const gp = require('geojson-precision')
const simplify = require('simplify-geojson')
const polyline = require('@mapbox/polyline')
const { createCanvas, loadImage } = require('canvas')
const { routes } = require('../utils/gpxutils.js')

const width = 1012
const height = 516

async function generate() {
  await Promise.all(
    routes.map(async route => {
      // simplify the geojson and strip extra points from coordinates to fit mapbox's api
      const geoJson = simplify(gp(route.geoJson, 4), 0.0001)
      // Encode our geoJson to a polyline - replace any "?" with encoded value or mapbox will break
      const poly = polyline.fromGeoJSON(geoJson.features[0].geometry).replace(/\?/g, '%3F')
      // Mapbox wants a hash-less hex value
      const color = route.color.replace('#', '')
      const padding = '80, 80, 120'
      const mapboxImage = `https://api.mapbox.com/styles/v1/mapbox/outdoors-v11/static/path-5+${color}-1(${poly})/auto/${width}x${height}?padding=${padding}&access_token=${process.env.NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN}`

      const canvas = createCanvas(width, height)
      const context = canvas.getContext('2d')

      // Load the mapbox image onto a canvas
      const map = await loadImage(mapboxImage)
      context.drawImage(map, 0, 0)

      // Add gradient in the bottom so overlayed text is visible
      const gradient = context.createLinearGradient(0, height * 0.7, 0, height)
      gradient.addColorStop(0, 'rgba(0,0,0,0)')
      gradient.addColorStop(1, 'rgba(0,0,0,0.5)')
      context.fillStyle = gradient
      context.fillRect(0, height * 0.7, width, height)

      // Add image in top corner
      const logo = await loadImage('./public/logo.png')
      context.drawImage(logo, 40, 40)

      const titleY = 470
      const labelY = titleY - 45
      const distanceX = 40
      const elevationX = width * 0.25 + distanceX
      const stifaX = width * 0.5 + distanceX
      const ratingX = width * 0.75 + distanceX

      // Add titles
      context.fillStyle = '#fff'
      context.font = 'bold 30pt Proxima Nova'
      context.fillText(`${Math.round(route.distance * 10) / 10} km`, distanceX, titleY)
      context.fillText(`${Math.round(route.elevation)} m`, elevationX, titleY)
      context.fillText(`${Math.round(route.elevation / route.distance)}`, stifaX, titleY)
      context.fillText(`${route.rating}/5`, ratingX, titleY)

      // Add labels
      context.font = 'bold 16pt Proxima Nova'
      context.fillText(`DISTANCE`, distanceX, labelY)
      context.fillText(`ELEVATION`, elevationX, labelY)
      context.fillText(`STIFA`, stifaX, labelY)
      context.fillText(`RATING`, ratingX, labelY)

      const buffer = canvas.toBuffer('image/png')
      fs.writeFileSync(path.join(process.cwd(), `public/og/${route.slug}.png`), buffer)
    }),
  )
}

generate()
```

That's quite a lot to take in so let's break it down step by step!

## Setup

In order to use Mapbox static image api you first need an access token. If you don't already have one you can get one from your [account page](https://account.mapbox.com/access-tokens/). 

The [Static Image API](https://docs.mapbox.com/help/glossary/static-images-api/) allows us to request a static map by providing a couple of parameters like coordinates & zoom level, but you can also add layers like paths and geoJson. 

Here's an example of a map generated with the following code:

```js
https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/
-122.337798,37.810550,9.67,0.00,0.00/1000x600?access_token=${MAPBOX_ACCESS_TOKEN}
```

<Image
  alt="Mapbox Static Api Example image"
  src={'/blog/mapbox-static-image-api/example.png'}
  width={1000}
  height={600}
/>

First we have specified the style of the map, in this case `streets-v11`. [Their documentation](https://docs.mapbox.com/api/maps/styles/#mapbox-styles) lists all the available styles. I've mainly used the `outdoors-v11` style but you can also desig a custom one specific for your needs. 

In this example we have used specific coordinates to specify what we want rendered but we can also make our map automatically fit the bounds to whatever is displayed, like geoJson or a path with the `auto` paramter.

## Using Mapbox's static api with geoJson

Our route data is in the form of a geoJson object. Check out my article [Building a mapping platform with React and Mapbox GL](https://kevchentw.com/blog/trailroutes) for details how to parse geoJson from gpx files.

The api supports geoJson using a `geoJson=({})` parameter, however it only accepts 8,192 or fewer characters. Even after simplifying the geojson and removing redundant coordinates to get it below the limit I did not manage to get it working. Instead I opted for the [Path](https://docs.mapbox.com/api/maps/static-images/#path) parameter which looks like this and accepts an encoded polyline:

```jsx
path-{strokeWidth}+{strokeColor}-{strokeOpacity}+{fillColor}-{fillOpacity}({polyline})
```

## Encoding geoJson to polyline

To create a polyline from geoJson we can use mapbox's polyline package. In order to make the polyline a bit more lean we can also simplify it with simplify-geojson and geojson-precision.

```jsx
const gp = require('geojson-precision')
const simplify = require('simplify-geojson')
const polyline = require('@mapbox/polyline')

routes.map(async route => {
  // simplify the geojson and strip extra points from coordinates to fit mapbox's api
  const geoJson = simplify(gp(route.geoJson, 4), 0.0001)
  // Encode our geoJson to a polyline - replace any "?" with encoded value or mapbox will break
  const poly = polyline.fromGeoJSON(geoJson.features[0].geometry).replace(/\?/g, '%3F')
})
```

<Warning type="info">
  It took me a while to figure out that the api does not accept polylines containing question marks "<strong>?</strong>" as that breaks the url parameters. Be sure to replace all instances with it's encoded counterpart.
</Warning>

Another thing we need to do is remove the `#` from the color we wish to have, specify the width and height and how much padding we want.

```jsx{10-15}
const gp = require('geojson-precision')
const simplify = require('simplify-geojson')
const polyline = require('@mapbox/polyline')

routes.map(async route => {
  // simplify the geojson and strip extra points from coordinates to fit mapbox's api
  const geoJson = simplify(gp(route.geoJson, 4), 0.0001)
  // Encode our geoJson to a polyline - replace any "?" with encoded value or mapbox will break
  const poly = polyline.fromGeoJSON(geoJson.features[0].geometry).replace(/\?/g, '%3F')
  // Mapbox wants a hash-less hex value
  const color = route.color.replace('#', '')
  // Extra padding in the bottom to make space for text
  const padding = '80, 80, 120'
  const width = 1012
  const height = 516
})
```

Now let's use the polyline in the api url and we have a working map 🎉

```jsx{16}
const gp = require('geojson-precision')
const simplify = require('simplify-geojson')
const polyline = require('@mapbox/polyline')

routes.map(async route => {
  // simplify the geojson and strip extra points from coordinates to fit mapbox's api
  const geoJson = simplify(gp(route.geoJson, 4), 0.0001)
  // Encode our geoJson to a polyline - replace any "?" with encoded value or mapbox will break
  const poly = polyline.fromGeoJSON(geoJson.features[0].geometry).replace(/\?/g, '%3F')
  // Mapbox wants a hash-less hex value
  const color = route.color.replace('#', '')
  // Extra padding in the bottom to make space for text
  const padding = '80, 80, 120'
  const width = 1012
  const height = 516
  const mapboxImage = `https://api.mapbox.com/styles/v1/mapbox/outdoors-v11/static/path-5+${color}-1(${poly})/auto/${width}x${height}?padding=${padding}&access_token=${MAPBOX_ACCESS_TOKEN}`
})
```

## Adding text on the image with node canvas

In order to add metadata like distance, elevation and logo on top of the image we can use [node-canvas](https://github.com/Automattic/node-canvas). It implements the web canvas API as closely as possible and is perfect for this use case. 

If you have ever used Sketch, Photoshop or another application that uses layers you can think of canvas the same way. What is written first (bottom of the layers list in sketch) is the bottom layer, and everthing after that is stacked on top. 

<Image
  alt="Sketch layers example"
  caption="Layers in Sketch"
  src={'/blog/mapbox-static-image-api/layers.png'}
  width={1406}
  height={592}
/>

In the code below I am adding a gradient *before* I add the text, that way the gradient will be positioned beneath the text in the final image.

I have commented what each line does in the code below. 

```jsx
// Create a canvas context the same size as out mapbox image
const canvas = createCanvas(width, height)
const context = canvas.getContext('2d')

// Load the mapbox image onto a canvas
const map = await loadImage(mapboxImage)
context.drawImage(map, 0, 0)

// Add gradient in the bottom so overlayed text is visible
const gradient = context.createLinearGradient(0, height * 0.7, 0, height)
gradient.addColorStop(0, 'rgba(0,0,0,0)')
gradient.addColorStop(1, 'rgba(0,0,0,0.5)')
context.fillStyle = gradient
context.fillRect(0, height * 0.7, width, height)

// Add logo in top left corner
const logo = await loadImage('./public/logo.png')
context.drawImage(logo, 40, 40)

// Specify the positions of the text overlays
const titleY = 470
const labelY = titleY - 45
const distanceX = 40
const elevationX = width * 0.25 + distanceX
const stifaX = width * 0.5 + distanceX
const ratingX = width * 0.75 + distanceX

// Add titles
context.fillStyle = '#fff'
context.font = 'bold 30pt Proxima Nova'
context.fillText(`${Math.round(route.distance * 10) / 10} km`, distanceX, titleY)
context.fillText(`${Math.round(route.elevation)} m`, elevationX, titleY)
context.fillText(`${Math.round(route.elevation / route.distance)}`, stifaX, titleY)
context.fillText(`${route.rating}/5`, ratingX, titleY)

// Add labels
context.font = 'bold 16pt Proxima Nova'
context.fillText(`DISTANCE`, distanceX, labelY)
context.fillText(`ELEVATION`, elevationX, labelY)
context.fillText(`STIFA`, stifaX, labelY)
context.fillText(`RATING`, ratingX, labelY)

const buffer = canvas.toBuffer('image/png')
// Write the image to a specified directory
fs.writeFileSync(path.join(process.cwd(), `public/og/${route.slug}.png`), buffer)
```

That's it! Find the full source code [here](https://github.com/samuelkraft/routes/blob/master/scripts/generate-images.js) and check out a few examples of images I generated:

<Image
  alt="A-trail + Gröna Trail Route"
  caption="A-trail + Gröna Trail Route"
  src={'/blog/mapbox-static-image-api/grona_atrail.png'}
  width={1012}
  height={516}
/>

<Image
  alt="Nyckelviken Trail Route"
  caption="Nyckelviken Trail Route"
  src={'/blog/mapbox-static-image-api/nyckelviken.png'}
  width={1012}
  height={516}
/>

<Image
  alt="Booleden + Värmdöleden Trail Route"
  caption="Booleden + Värmdöleden Trail Route"
  src={'/blog/mapbox-static-image-api/booleden_varmdoleden.png'}
  width={1012}
  height={516}
/>

If you liked this post please let me know by pressing ❤️ below!


I built <a href="https://routes.kevchentw.com">Trail Routes</a> as a way to share some of the best running & hiking routes I've discovered, and in this post I will outline the build process.

## The goal
My goal was to show a list of routes I enjoy coupled with basic information like distance, elevation gain and my rating. The routes should be visible on a map, and clicking a route should display more information about it, including an elevation map. There should be a way to download each route as a gpx file.
<Warning type="info">
    A gpx file is basically an xml file consisting of coordinates that forms a route. It can also contain other information like heart rate data and elevation if created from an activity. You can transfer gpx files to most modern sport watches and get navigation features.
</Warning> 

I opened up Sketch to create a logo and a few mockups of the interface:

<Image
  alt="Trail Routes logo"
  caption="Logotype"
  src={'/blog/trailroutes/logo.png'}
  width={1416}
  height={707}
/>
<Image
  alt="Trail Routes main view mockup"
  caption="Main view"
  src={'/blog/trailroutes/trailroutes-mockup.png'}
  width={1416}
  height={707}
/>
<Image
    alt="Trail Routes detail view mockup"
    caption="Detail view"
    src={'/blog/trailroutes/trailroutes-mockup-detail.png'}
    width={1416}
    height={707}
/>

## Getting the route data
I create all my routes with Stravas Route builder tool which uses Mapbox so that seemed like a great choice for me as well. In order to display things on a Mapbox map you need the data as a geoJson object. My first idea was to use the strava API to fetch the routes I've created, which then returns the data in a mapbox-friendly format. This didn't work very well because I have created TONS of routes on Strava, and unfortunately there's no way to tag or categorise them so I started looking at alternatives. 

That's when I found Mapbox's package [toGeoJson](https://github.com/mapbox/togeojson) that takes a GPX file and converts it to geoJson, just what is needed! The code below looks at a public/gpx folder, maps over the files and pulls out the geoJson and creates a slug for each route.

```jsx
import toGeoJson from '@mapbox/togeojson'
import { DOMParser } from 'xmldom'
import path from 'path'
import fs from 'fs'

const ROUTES_PATH = path.join(process.cwd(), 'public', 'gpx')

const routes = routeFilePaths.map(filePath => {
    const source = new DOMParser().parseFromString(fs.readFileSync(path.join(ROUTES_PATH, filePath), 'utf8'))
    const geoJson = toGeoJson.gpx(source)
    const slug = filePath.replace('.gpx', '')

    return {
        geoJson, slug	
    }
})
```

## Calculate geoJson distance with Turf.js

The gpx files from Strava only contains cordinates and some basic metadata, but we're missing distance and total elevation. Luckily we can use an amazing open-source project called [Turf.js](http://turfjs.org) to do lots of advanced analysis on our geoJson. Look how easily we can calculate the total distance of the geoJson using [@turfjs/length](https://www.npmjs.com/package/@turf/length):

```jsx{5,14-15,18}
import toGeoJson from '@mapbox/togeojson'
import { DOMParser } from 'xmldom'
import path from 'path'
import fs from 'fs'
import length from '@turf/length'

const ROUTES_PATH = path.join(process.cwd(), 'public', 'gpx')

const routes = routeFilePaths.map(filePath => {
    const source = new DOMParser().parseFromString(fs.readFileSync(path.join(ROUTES_PATH, filePath), 'utf8'))
    const geoJson = toGeoJson.gpx(source)
    const slug = filePath.replace('.gpx', '')

    // Calculate distance using geoJson
    const distance = length(geoJson)

    return {
        geoJson, slug, distance
    }
})
```

## Parse elevation data from geoJson

The original gpx file from strava contains the current elevation for each point, so in order to calculate the total elevation gain we simply map over the coordinates and sum the difference between each as explained in [this article](https://www.gpsvisualizer.com/tutorials/elevation_gain.html). Credit to Taylor Callsen's [initial implemention](https://github.com/tcallsen/geoCalcLineElevation).

```jsx{9-16,19}
const routes = routeFilePaths.map(filePath => {
    const source = new DOMParser().parseFromString(fs.readFileSync(path.join(ROUTES_PATH, filePath), 'utf8'))
    const geoJson = toGeoJson.gpx(source)
    const slug = filePath.replace('.gpx', '')

    // Calculate distance using geoJson
    const distance = length(geoJson)

    // Calculate elevation gain using coordinate data
    const { coordinates } = geoJson.features[0].geometry
    let elevation = 0
    coordinates.forEach((coord, index) => {
      if (index === coordinates.length - 1) return // stop 1 point early since comparison requires 2 points
      const elevationDifference = coordinates[index + 1][2] - coordinates[index][2]
      if (elevationDifference > 0) elevation += elevationDifference
    })

    return {
        geoJson, slug, distance, elevation
    }
})
```

That's a lot of parsing and calculation! 😅 I now realized that my choice of using Next.js was a perfect fit for the project. All the parsing can be done at build time inside getInitialProps, and then I can serve a static cached version of the site for all visitors. 

## Displaying geoJson with Mapbox GL and React

I used the excellent guide from the Mapbox docs on [creating a mapbox react component](https://docs.mapbox.com/help/tutorials/use-mapbox-gl-js-with-react/). Mapbox's outdoor map is perfect for this use-case and can be accessed by setting the style to outdoors:
```jsx{3}
const map = new mapboxgl.Map({
    container: mapContainer.current,
    style: 'mapbox://styles/mapbox/outdoors-v11',
    center: [lng, lat],
    zoom,
  })
```

We want to add all our geoJson to the map when it has finished loading by mapping over the routes in a `map.on('load')` callback. 

There's two steps to displaying geoJson on the map:

1. Add the source
2. Add a layer using that source

```jsx
map.on('load', () => {
  routes.forEach((route: Route) => {
    const { slug } = route
	// 1. Add the source using the slug as unique id
    map.addSource(slug, {
      type: 'geojson',
      data: route.geoJson,
    })

    // 2. Add a layer displaying our route
    map.addLayer({
      id: slug,
      type: 'line',
      source: slug, // same id as above
      layout: {
        'line-join': 'round',
        'line-cap': 'round',
      },
      paint: {
        'line-color': 'red',
        'line-width': 4,
      },
    })
})
```

We should now have a map showing all our routes 🎉 Right now the color is hardcoded to red, in order differentiate we need to specify a color for each route. In my case I'm saving some extra metadata in a javascript file including a custom color for each:

```js{8,14}
const colors = require('tailwindcss/colors')

export const meta = {
  nyckelviken: {
    description: '…',
    rating: 5,
    location: 'Nacka · Stockholm',
    color: colors.blue[500],
  },
  hellasgarden_gula: {
    description: '…',
    rating: 5,
    location: 'Nacka · Stockholm',
    color: colors.yellow[300],
  }
}
```
```jsx{10}
map.addLayer({
  id: slug,
  type: 'line',
  source: slug,
  layout: {
    'line-join': 'round',
    'line-cap': 'round',
  },
  paint: {
    'line-color': color,
    'line-width': 4,
  },
})
```

## Updating our mapbox map with react

The final feature for our map component is to be able to click each route and the map to zoom in to just that route.
In order to get a bigger click area than just the line we added before we can add a transparent fill inside each route:

```jsx
// Add a fill layer as source for hover, or we lose our click target when inside the path
map.addLayer({
  id: `${slug}-fill`,
  type: 'fill',
  source: slug,
  paint: {
    'fill-color': 'transparent',
    'fill-outline-color': 'transparent',
  },
})
```

Then when we hover and click that element we can trigger an action, in this case updating our query.

```jsx

map.on('mouseenter', `${slug}-fill`, () => {
  // Change the cursor style as a UI indicator.
  map.getCanvas().style.cursor = 'pointer'
  // Increase width of route path
  map.setPaintProperty(slug, 'line-width', 6)
})

map.on('mouseleave', `${slug}-fill`, () => {
  map.getCanvas().style.cursor = ''
  map.setPaintProperty(slug, 'line-width', 4)
})

map.on('click', `${slug}-fill`, () => {
  const coords = route.geoJson.features[0].geometry.coordinates
  // Calculate the bounds to know where to zoom to
  const bounds = coords.reduce((b, coord) => {
    return b.extend(coord)
  }, new mapboxgl.LngLatBounds(coords[0], coords[0]))

  // Fit map to bounds/route
  map.fitBounds(bounds, {
    padding: 20,
  })
	
  // Update the query
  router.push({ query: { route: slug } })
})
```

Now we just need to remove the other routes from the map. We could do this in the onclick above - but that won't work if we link directly to a specific route (e.g. <a href="https://routes.kevchentw.com/?route=nyckelviken">https://routes.kevchentw.com/?route=nyckelviken</a>). In order to solve this we can add a useEffect instead with the current query as a dependency. Every time the route/query is updated our function will run and update the visible route on the map. The simplest way i found to remove the non-active routes was not to remove the layers but to simply update the layer's visibility to none. In order to get access to our `map` object that's only accessible in the original effect we can save it in a local state variable. 

```jsx

const router = useRouter()
const queryRoute = router.query.route

const [stateMap, setStateMap] = useState(null)

useEffect(() => {
  const map = new mapboxgl.Map({
    container: mapContainer.current,
    style: 'mapbox://styles/mapbox/outdoors-v11',
    center: [lng, lat],
    zoom,
  })
	
	setStateMap(map) // save our map to state to get acces in other useEffects

	return () => map.remove()
}, [])

useEffect(() => {
    if (queryRoute && stateMap) {
      routes.forEach((route: Route) => {
        const { slug } = route
				
		  // Set the current query route as visible
      if (slug === queryRoute) {
        stateMap.setLayoutProperty(slug, 'visibility', 'visible')
        stateMap.setLayoutProperty(`${slug}-fill`, 'visibility', 'visible')

        const coords = route.geoJson.features[0].geometry.coordinates
        const bounds = coords.reduce((b, coord) => {
          return b.extend(coord)
        }, new mapboxgl.LngLatBounds(coords[0], coords[0]))

        // Fit map to bounds/route
        stateMap.fitBounds(bounds, {
          padding: 20,
        })
      } else {
		  // Hide the rest of the routes
          stateMap.setLayoutProperty(slug, 'visibility', 'none')
          stateMap.setLayoutProperty(`${slug}-fill`, 'visibility', 'none')
        }
      })
    } else {
	  // if no selected route then show all routes and restore the zoom to intial bounds
      routes.forEach((route: Route) => {
        const { slug } = route
        if (stateMap) {
          stateMap.setLayoutProperty(slug, 'visibility', 'visible')
          stateMap.setLayoutProperty(`${slug}-fill`, 'visibility', 'visible')
          stateMap.flyTo({
            center: [lng, lat],
            essential: true,
            zoom,
          })
        }
      })
    }
  }, [queryRoute, stateMap])
```

That's it for the map component!

## Styling with Tailwind CSS

To finalise the app I added the list of routes as a sidebar and styled it with [Tailwind CSS](https://tailwindcss.com). When you click a route and the query changes I used Framer Motion to add a slide animation showing a detail view with the meta information. One issue I had was that the original list was often longer than the detail view and when simply moving it to the side it would still take up space and increase the scrollable portion of the page. The solution to this is to add a `transitionEnd` property to our animation setting the element to display none.

```jsx
<motion.div
  animate={
    queryRoute
      ? {
          x: '-30%',
          scale: 0.95,
          transitionEnd: {
            display: 'none', // Completely remove sidebar from the DOM when animation finishes
          },
        }
      : { x: 0, scale: 1, display: 'block' }
  }
  transition={{ ease: 'easeOut', duration: 0.2 }}
>
	// sidebar content
</motion.div>

{queryRoute && (
	<motion.div
	    className="w-full absolute top-0 min-h-screen bg-white -ml-5 -mr-5 px-5"
	    initial={{ x: 430 }}
	    animate={{ x: 0 }}
	    transition={{ ease: 'easeOut', duration: 0.2 }}
	  >
		// detail view content
	</motion.div>
)}
```

## Wrapping up

The last thing I did was create some nice assets, like a favicon and a meta sharing image. Check out <a href="https://routes.kevchentw.com">Trail Routes</a> and let me know if you enjoyed this write-up by pressing like below!

<Image
alt="Trail Routes og image"
caption="Sharing image"
src={'/blog/trailroutes/og.png'}
width={1012}
height={506}
/>