Creating a bespoke style in Maputnik

Creating a bespoke style for the OS Vector Tile API

This ‘how-to’ will show you how to create your own style for the OS Vector Tile API which you can then use in Web Maps and GIS software.

To do this, we recommend using the open source visual editor, Maputnik - Maputnik.

It is important to note that the OS Vector Tile API only works in epsg: 3857 (Web Mercator) in Maputnik. If you want to create a style for the epsg: 27700 (British National Grid) version of the OS Vector Tile API, please contact the Geographic Data Visualisation Team at OS (geodataviz@os.uk) who will advise you further.

More information about the OS Vector Tile API can be found here: OS Vector Tile API | OS APIs

Loading Vector Tiles into Maputnik

Go to https://maputnik.github.io/ and click on ‘Editor’ at the top.

We recommend starting with one of our existing styles as a basis for creating your own style. These are available in our GitHub repo.

Go to the OS-Vector-Tile-API Stylesheets Repo in GitHub: OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets: Cartographic stylesheets for use with OS Vector Tile API

Click on the style you want (only the 3857 ones work in Maputnik).

A window with the json will open. At the top of this window, click on ‘Raw’

Copy the url for this json file.

Back in Maputnik, go to Open and then paste your style url into the ‘Load from URL’ box.

Click ‘Load from URL’.

You will now see various map layers displayed in the ‘Layers’ panel on the left hand side. The map will be blank at the moment – don’t worry, we’ll fix this next.

Fixing the sprites and glyphs

Go to ‘Data Sources’ in the top toolbar.

Add ?srs=3857&key=INSERT_API_KEY_HERE to the TileJSON URL

?srs=3857&key=CuDdvyI6HXxBdScA4d7A7q8jGG4I1gYA

It should now read: https://api.os.uk/maps/vector/v1/vts?srs=3857&key=INSERT_API_KEY_HERE

Next go to ‘Style Settings’ in the top toolbar

Add ?srs=3857&key=INSERT_API_KEY_HERE to the Glyphs URL

It should now read: https://api.os.uk/maps/vector/v1/vts/resources/fonts/{fontstack}/{range}.pbf?srs=3857&key= INSERT_API_KEY_HERE

Hit ‘Enter’, close the Style Settings and your map should now appear in the Map view.

Editing the map style

3.1 Layer Styling

Using the Layers panel on the left, click on the layer you want to alter.

You can also click on features on the map to find out what layer they are in. When you click on a feature on the map, a pop-up box will appear with all the layers available where you clicked. You can select the layer name in the map view pop-up and it will open that layer in the Layers panel on the left.

You can now use the Paint Properties in the editing panel on the left to alter the styling of these features. The colour of the features is quick and easy to change using the ‘Color’ property – click on the rgb value to open up a colour selector window.

There are many things you can change in maputnik with regard to styling. This includes the opacity of layers, the style of features at different zoom levels and what features appear at various zoom levels. It is also possible to filter the data based on an attribute value.

In the example below, we have filtered the roads layer to _symbol == 3 which identifies and filters out just Primary Roads. We have also adjusted the zoom levels such that our primary roads appear at zoom level 8 and disappear at zoom level 16.

You can also change the colour of features with zoom level by clicking the ∑ symbol next to Color and setting the rgb value for each zoom level. You can do the same with the Width of line features by clicking the ∑ symbol next to the Width and setting the width values for each zoom level.

In the Layers panel you can add new layers, rearrange your layers, hide layers, duplicate layers and remove layers.

3.2 Spritesheets (Symbols)

A spritesheet is a single image file that contains multiple smaller graphics or sprites. Sprites are used to create both point symbols and pattern fills and are used in Vector Tiles to determine the symbology. Unfortunately, they cannot be edited directly in Maputnik.

If you open up one of the style json files, you will see that they reference a spritesheet.

We recommend using one of our existing spritesheets for ease – we have these in full colour, greyscale and dark available in our GitHub Repo: OrdnanceSurvey/OS-Vector-Tile-API-Stylesheets: Cartographic stylesheets for use with OS Vector Tile API.

In order to create your own bespoke symbology, you’ll either need to edit one of our existing spritesheets in an image editing software such as Adobe Photoshop or use Spreet (https://crates.io/crates/spreet) to create your own.

You will need to host the spritesheet somewhere (e.g. Github) before they can be used in Maputnik and you’ll need to reference this new spritesheet in the style json.

3.3 Glyphs (Fonts)

In Maputnik, glyphs essentially defining how letters, numbers, and symbols appear, and are typically loaded from a dedicated font file specified in your map style. This allows you to customize the appearance of text labels on your map by choosing different fonts and adjusting their properties within the Maputnik editor.

You define which font to use for your map labels by specifying a "glyphs" property in your style JSON, pointing to a URL where the font data is hosted.

We generally recommend that you use our existing glyphs, as defined in the Vector Tile style json (you can change their size and colour in Maputnik). However, if you want to create your own, new glyphs can be generated using font-maker (https://maplibre.org/font-maker/) and will need to be hosted somewhere before use. Again, you’ll need to reference the glyph file in the style json.

Exporting your style

When you are happy with all of the changes you have made, go to ‘Save’ in the top toolbar and then ‘Save As’. Save your json file to the location of your choosing.

If you want to use your new style in a GIS package such as QGIS (supports epsg: 3857 only) or Esri ArcPro (supports epsg: 27700 only), you will need to host your stylesheet somewhere, along with the glyphs and spritesheets.

You can read more about using bespoke Vector Tile styles in GIS software (including our pre-defined styles available on GitHub) here: