Add text to a static map image
Familiarity with front-end development concepts. Some JavaScript required.
This tutorial will show how to build a webpage which displays a map image from the Mapbox Static Images API overlaid with text.
The Static Images API renders images from map styles and supports a few overlay types, including markers, paths, and GeoJSON. Text/label overlays are not supported, so this tutorial demonstrates a workaround to add text to a static image in a web browser using an HTML canvas element.
If you're new to the Static Images API, you might want to read about making a Static Images API call first. You can also experiment with the API using the Static Images API Playground.
Get started
There are a few resources you'll need before getting started:
- An access token from your Mapbox account. The access token is used to authenticate your account when making API calls and you can find it on your Account page.
- A text editor You'll be writing HTML, CSS, and JavaScript.
Create the document
Before you write the JavaScript and make the API call that will result in a Static Image appearing on your webpage, you need to set up an HTML page.
Create an HTML file
Create a file called index.html. Then, add the following boilerplate HTML to your document, setting up a blank webpage.
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="robots" content="noindex, nofollow" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>Demo: Add text to a static map image</title>
</head>
<body></body>
</html>
Next, create a canvas element in the body of your HTML file. This will serve as the container for your static map image, and should have the same dimensions.
<canvas id="canvas" width="534" height="400"></canvas>
Next, add styles to your canvas via style tags in the head of your HTML. This ensures that your map image will be centered on the webpage. Below all other elements in your head, insert the following.
<style>
canvas {
background-color: white;
position: absolute;
inset: 0;
margin: auto;
}
</style>
Add the static map image to the canvas
Next, you will need to add JavaScript to make the API call required for the static map image. You will need to select the canvas, create an image, give the image a source, and finally add the image to the canvas. To do so, add the following to the body underneath the canvas element.
<script>
function draw() {
const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');
const img = new Image();
img.addEventListener('load', () => {
ctx.drawImage(img, 0, 0, 534, 400);
});
img.src = `https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/pin-m+3fb1ce(-71.34694,43.58794)/-70.9793,44.5397,3.86,0/534x400@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN`;
}
window.onload = draw;
</script>
Note that the marker is an optional parameter of the Static Images API; it is added to the map via /pin-m+3fb1ce(-71.34694,43.58794) in the API call, which defines its size, color, and location. You can experiment with API calls with the Static Images API Playground.
Add text to the canvas
You will add text inside of the canvas after the loading of the image. Inside the load event listener, add the following after the call to drawImage().
ctx.font = '18px verdana';
ctx.textAlign = 'center';
ctx.fillText('Lake Winnipesaukee', 267, 175);
Note that the coordinates 267, 175 place the text directly above the marker in the provided API call. If you have a differently-sized image or a different map, you will need to change these coordinates to make sure that the text is placed in the correct location. ctx.font and ctx.textAlign allow you to configure the style and position of the text.
Add an outline and shadow to improve readability
The text has appeared, but adding styles to it can make it clearer to read. The following code adds a white stroke (outline) and a blurred shadow, making the dark text more readable.
// set font and alignment
ctx.font = '18px verdana';
ctx.textAlign = 'center';
// add light shadow and stroke
ctx.shadowColor = '#FFF';
ctx.strokeStyle = '#FFF';
ctx.shadowBlur = 4;
ctx.lineWidth = 2;
ctx.strokeText('Lake Winnipesaukee', 267, 175);
// dark text
ctx.fillStyle = '#000';
ctx.fillText('Lake Winnipesaukee', 267, 175);
Finished product
You created a webpage showing a static map image from the Mapbox Static Images API with a text overlay. The image includes a marker at a specific point of interest and the text provides additional context.
This technique of using an HTML canvas to add text to an image is also possible without a web browser. For example, the node-canvas package allows for this kind of image manipulation in a Node.js environment. This may be a more practical approach for programmatically creating static map images with overlay text, depending on your use case.
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<title>Demo: Add text to a static map image</title>
<style>
canvas {
background-color: white;
position: absolute;
inset: 0;
margin: auto;
}
</style>
</head>
<body>
<canvas id="canvas" width="534" height="400"></canvas>
<script>
function draw() {
const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');
const img = new Image();
img.addEventListener('load', () => {
// add the image to the canvas
ctx.drawImage(img, 0, 0, 534, 400);
// set font and alignment
ctx.font = '18px verdana';
ctx.textAlign = 'center';
// add light shadow and stroke
ctx.shadowColor = '#FFF';
ctx.strokeStyle = '#FFF';
ctx.shadowBlur = 4;
ctx.lineWidth = 2;
ctx.strokeText('Lake Winnipesaukee', 267, 175);
// dark text
ctx.fillStyle = '#000';
ctx.fillText('Lake Winnipesaukee', 267, 175);
});
img.src = `https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/pin-m+3fb1ce(-71.34694,43.58794)/-70.9793,44.5397,3.86,0/534x400@2x?access_token={{MAPBOX_ACCESS_TOKEN}}`;
}
window.onload = draw;
</script>
</body>
</html>
Next steps
With this guide, you have the tools to create a static map image with overlay text. Explore more Static Images API resources on our Help page and see the full Static Images API documentation and tutorials for more inspiration and guidance.