# Creating a bespoke style for the OS NGD API – Tiles

OS NGD API – Tiles provides you with a lightweight and easy to use basemap.

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

To do this, we recommend using the open source visual editor - [Maputnik](https://maputnik.github.io/).

It is important to note that the OS NGD API – Tiles 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 NGD API – Tiles, please contact the Geographic Data Visualisation Team at OS (<geodataviz@os.uk>) who will advise you further.

More information about the NGD API – Tiles Tile API can be found [here](https://docs.os.uk/osngd/getting-started/access-the-os-ngd-api/os-ngd-api-tiles).

### **Loading the OS NGD API** – **Tiles Style into Maputnik**

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

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-6558973a73ca4b8eed8e70c2e4be6d694f4b203b%2FMaputnik_Tiles%20_API_1.png?alt=media" alt="Image of the Maputnik Editor"><figcaption><p>Maputnik Editor</p></figcaption></figure>

We recommend starting with one of our existing styles as a basis for creating your own style. We have 4 house styles to choose from – light, road, outdoor and black & white.

Select one of the style URLs from the list below:

**Black and White:** <mark style="color:red;"><https://api.os.uk/maps/vector/ngd/ota/v1/collections/ngd-base/styles/blackwhite-3857></mark>

**Light:** <mark style="color:red;"><https://api.os.uk/maps/vector/ngd/ota/v1/collections/ngd-base/styles/light-3857></mark>

**Road:** <mark style="color:red;"><https://api.os.uk/maps/vector/ngd/ota/v1/collections/ngd-base/styles/road-3857></mark>

**Outdoor:** <mark style="color:red;"><https://api.os.uk/maps/vector/ngd/ota/v1/collections/ngd-base/styles/3857></mark>

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

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-47d3b4471aae9f3a2931978e9dcc8dd344bcaff6%2FMaputnik_Tiles%20_API_2.png?alt=media" alt="Maputnik interface loading from a URL"><figcaption><p>Load from URL</p></figcaption></figure>

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.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-e86b79cd38224ca15ab5bf73d18e8b6cf378fbbd%2FMaputnik_Tiles%20_API_3.png?alt=media" alt="image of the maputnik layers panel"><figcaption><p>Layers panel</p></figcaption></figure>

### Adding the Tile Location

Go to ‘Data Sources’ in the top toolbar.

Delete the current active source which is called #ngd-base.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-81a951da786289fa4e1da4893ae7a0b5dd3b6bd7%2FMaputnik_Tiles%20_API_4.png?alt=media" alt="image of the maputnik active data sources"><figcaption><p>Active data sources</p></figcaption></figure>

Add a new source using the parameters below:

**Source ID:** ngd-base

**Source Type:** Vector (Tile URLs)

**Tile URL:** <https://api.os.uk/maps/vector/ngd/ota/v1/collections/ngd-base/tiles/3857/{z}/{y}/{x}?key=> {INSERT\_YOUR\_API\_KEY\_HERE}

**Scheme Type:** xyz (Slippy map tilenames scheme)

**Min Zoom:** 6

**Max Zoom:** 19

Click ‘Add Source’

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-cb64136042b1d501516974cbc0ce0fd3ee8b62ba%2FMaputnik_Tiles%20_API_5.png?alt=media" alt="Maputnik Add Source dialogue"><figcaption><p>Add new source</p></figcaption></figure>

Close the Source window. A map may now have appeared in your map view. If it hasn’t this is likely because you’re zoomed to somewhere outside the mapping area.

In the URL for the page, change the end part of the URL to #17/50.727589/-3.541809

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-e7fbfa5ea18c26594d8124fbe3ae825779fd0e78%2FMaputnik_Tiles%20_API_6.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-555f8ab98f3ad87d5473399c5896a89844d7717b%2FMaputnik_Tiles%20_API_7.png?alt=media" alt=""><figcaption></figcaption></figure>

Hit ‘Enter’ and your page should now refresh and load the API mapping.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-e097d1e1e43059de9226c63fcdbc0722f9bc36d1%2FMaputnik_Tiles%20_API_8.png?alt=media" alt="image of the maputnik with API map data loaded"><figcaption><p>API map data</p></figcaption></figure>

### Editing the Map Style

**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.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-6a074eee076d31952b486ba937586ffcaf1bb3e6%2FMaputnik_Tiles%20_API_9.png?alt=media" alt="Selecting a layer in Maputnik"><figcaption><p>Select layer</p></figcaption></figure>

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.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-b688253380816fbf94b603301338be34a6fd781f%2FMaputnik_Tiles%20_API_10.png?alt=media" alt="changing the paint properties of a layer in Maputnik"><figcaption><p>Paint properties</p></figcaption></figure>

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-5a7261f55d4bacb68f0c261d6dc90302b6edc389%2FMaputnik_Tiles%20_API_11.png?alt=media" alt="Building colour now changed in Maputnik"><figcaption><p>Building colour</p></figcaption></figure>

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.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-451dcb91b2c0b6b1ab1eac0e87b5265329676291%2FMaputnik_Tiles%20_API_12.png?alt=media" alt="Maputnik Layer options dialogue"><figcaption><p>Layer options</p></figcaption></figure>

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.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-b6ad0f99ca34267f064d1774989e48702dc22202%2FMaputnik_Tiles%20_API_13.png?alt=media" alt="Dialogue box for changing paint properties by zoom level"><figcaption><p>Paint properties by zoom level</p></figcaption></figure>

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-9635d22fa5830ee41cd013a77cc31de912aa6031%2FMaputnik_Tiles%20_API_14.png?alt=media" alt="Changing width of feature based on its zoom level"><figcaption><p>Changing width of feature based on its zoom level</p></figcaption></figure>

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

**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.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-6e1ce6e36d8d2b97e684a5f9c0f879a04106835e%2FMaputnik_Tiles%20_API_15.png?alt=media" alt="Image of a json file highlighting a reference to a Spritesheet"><figcaption><p>Spritesheet</p></figcaption></figure>

We recommend using one of our existing spritesheets. 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.

**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 OS NGD API – Tiles 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.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-57a1cf4e4f60d83c5c95eb63a237ec9fa5df8518%2FMaputnik_Tiles%20_API_16.png?alt=media" alt="Image of a json file highlighting a reference to a glyph file"><figcaption></figcaption></figure>

### 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) you will need to host your stylesheet somewhere and then you can use the json URL as the Style URL when setting up your API connection.