1 of 26

Accessing OS NGD APIs

The following pages provide an overview of the OS National Geographic Database (NGD) APIs and how you can access them. They cover the core elements of the design (including data available), technical specifications, and how to get started, amongst other topics.

These pages should be used in conjunction with the more detailed pages within the Data Structure section which are specifically focussed on the different OS NGD themes, collections and feature types.

The APIs are self-documenting and allow you to easily discover what OS NGD data is available before using it. You can explore the various data collections for free to decide what best suits your needs. The data is ready to use in numerous applications (desktop, web, and mobile), enabling you to power your applications with rich, consistent and current information about the real world.

The OS NGD APIs are available via the OS Data Hub.

OS NGD API – Features

What is OS NGD API – Features?

With OS NGD API – Features, you can filter by attribute, location and / or time to create your own customised data selections. Based on the latest OGC API – Features standard, this API can help accelerate your time-to-value by making it easier to build awesome things with our trusted geospatial data. You can use it to reduce your data management overheads, automate your workflows, and innovate at pace.

Benefits

Things to remember for OS NGD API – Features

You can:

Request specific features using location, attribute, and / or time queries.
Interrogate highly detailed feature information.
Freely discover what OS NGD data collections are available.
Explore the OS NGD data schemas and queryables.
Request data in GeoJSON format.
Visualise OS data and apply your own styling.

You can't:

Create a scalable map of Great Britain across zoom levels.
Request more than 100 features in a single transaction.
Access data from the:
- OS NGD Address Theme
- OS NGD Administrative and Statistical Units Theme
- Waterbody Catchment and River Basin District Catchment Feature Types (of the OS NGD Water Features Collection in the OS NGD Water Theme)

If you are interested in addressing information, OS Places API provides a detailed view of an address and its lifecycle, giving you direct access to rich address data for geocoding, postcode searching, form-filling and much more.

What data is available?

What feature types are available in OS NGD API – Features?

The following table documents the OS NGD datasets available through the OS NGD API – Features showing the themes, collections and lists the available feature types.

OS NGD themes and collections have been created to group similar geographic entities and data types, making it quicker and easier to identify the data you need. The OGC API - Features standard also references feature collections, and in the context of OS NGD datasets, this is equivalent to feature types.

The following naming convention has been applied to the feature collections: theme-collection-featuretype-version. Short codes have been used for both the theme and collection to keep the feature collection names manageable and not overly long. An example of the short codes used is below:

bld-fts-buildingline-1

Click on the theme to find out more information about the dataset:

Theme

Collection

Feature Type(s)

Find out more about the hierarchy of OS NGD data .

If you are interested in addressing information, provides a detailed view of an address and its lifecycle, giving you direct access to rich address data for geocoding, postcode searching, form-filling and much more.

Technical Specification

API Reference

OS NGD API – Features Technical Specification provides an overview of the endpoints available, as well as the parameters that can be used with each endpoint. The Technical Specification is intended to be used by customers who want to integrate with the API. Click into each endpoint to learn more.

Use of CQL Operators

The OS NGD API – Features supports a generic filter grammar called Common Query Language (CQL) for specifying enhanced filter criteria to return a subset of features. CQL is written using a familiar text-based syntax, making it more readable and better-suited for creating complex filters.

The following table documents the supported operators:

Operator Type

Supported Operators

Comparison

EQUAL TO [ = ], LESS THAN [ < ], LESS THAN OR EQUAL TO [ <= ], GREATER THAN [ > ], GREATER THAN OR EQUAL TO [ >= ], ISNULL, LIKE, IN, BETWEEN

Logical

AND, OR, NOT [ <> ]

Array

AEQUALS, ACONTAINS, ACONTAINEDBY, AOVERLAPS

Spatial

INTERSECTS

Getting Started

The following pages provide an overview of how to get started using OS NGD API – Features. They provide step-by-step instructions to get started in the most common and .

These pages should be read in conjunction with the more detailed pages within the section and the API's .

GIS Software

Accessing OS NGD data with OS NGD API – Features via GIS software

The following sub-sections provide step-by-step instructions on how to access OS NGD data via OS NGD API – Features in various GIS software packages:

Cadcorp SIS
ESRI ArcGIS Online
ESRI ArcGIS Pro
QGIS

Cadcorp SIS

Accessing OS NGD data with OS NGD API – Features via Cadcorp SIS

The Cadcorp Spatial Information System® (Cadcorp SIS®) is an integrated family of geospatial products comprising desktop, web, and developer applications.

Cadcorp SIS Desktop connects directly to the OS Data Hub through dedicated wizards.

What you need

Cadcorp SIS (version SIS 9 or later).
A preloaded base map, for example, or .
OS NGD API – Features added to an API project in the OS Data Hub with an API Key. See for more information.

Instructions

These instructions are based on Cadcorp SIS Desktop version 9.1.1668.

Add overlay

Once a new map has been set up, in the Home tab, click Add Overlay.

Select API

In the Overlay Types dialog:

Select Ordnance Survey (GB) > OS (GB) Data Hub, and then click Next.

In the OS (GB) Data Hub dialog:

Select OS National Geographic Database (NGD) API – Features.
API Key: Enter your API key.
Premium/Public Sector Plan: Select this option if you have this plan.
Save in the UI settings database (encrypted): Select this option.
Click Next.

Adding layers to the map

In the OS Data Hub NGD API – Features Data Themes and Feature Types dialog:

Well-known ‘recipe’: Select a predefined recipe, if available.
Data Themes: Select your data themes.
Features: If necessary, use the editing tools (on the right) to delete feature types or to change the order in which they display in your SIS Workspace Definition (SWD). By default, all feature types within the selected data themes are available in the right panel.
Local cache: Select this option to store the data temporarily on your machine. If you save and reopen the SWD, the data will still be available as it is fetched from your local cache.
One-off import: Select this option to do a one-off import of the data. If you save and reopen the SWD, the data will not be available and you will need to re-import it. These imports have a larger file size.
Filtering: These settings are used in conjunction and define how much data is required for display. It is recommended that you always set a spatial filter and feature limit.
- Spatial: The Intersect with current view extent option limits the download to only selected features within the current window extent. You can also load features within a specific area of interest using the polygon feature to draw your area of interest on the map BEFORE opening the Add Overlay dialog.
- Maximum number of features: Limits the number of feature values downloaded to the number set. This limit is applied per feature within any filtered spatial area.
Click Finish.

The selected layer(s) will then display in the SIS Workspace Definition (SWD) and the data will display in the map area:

ESRI ArcGIS Online

Accessing OS NGD data with OS NGD API – Features via ESRI ArcGIS Online

ArcGIS Online is a web-based platform geographic information system (GIS). ArcGIS Online services are managed by Esri and accessed by a client running on a wide range of options.

The instructions that follow demonstrate how to connect to OS NGD API – Features using ESRI ArcGIS Online.

What you need

Access to the ESRI ArcGIS Online service.
A preloaded base map, for example, .
OS NGD API – Features added to an API project in the OS Data Hub with an API Key. See for more information.

Instructions

Add a new layer

Once you've signed into your ESRI ArcGIS Online account and opened the map viewer. Zoom in to a small area to reduce the number of requests that are initially sent to the API.

Select Layers > Add > Add layer from URL.

Add an API and set up custom parameters

In the Add Layer dialog:

URL: Enter the base URL for OS NGD API – Features, excluding the API Key. For example, https://api.os.uk/features/ngd/ofa/v1.
Type: Select OGC feature layer.
Select Custom request parameters and enter the following:
- Parameter: key
- Value: [Insert your OS API Key here]
Click Next.

Adding layers to the map

In the Add Layer dialog:

To add a layer to the map: Select a layer to add to the map and then click Add to map.

The layer will then display in the Layers panel and the data will display on the map:

Features will automatically refresh when you zoom or pan on the map. If you wish to add multiple layers to the same map, repeat steps 2 and 3.

ESRI ArcGIS Pro

Accessing OS NGD data with OS NGD API – Features via ESRI ArcGIS Pro

ESRI ArcGIS Pro is a desktop geographic information system (GIS) application that allows users to maintain, visualise and analyse spatial data.

The instructions that follow demonstrate how to connect to OS NGD API – Features using ESRI ArcGIS Pro.

What you'll need

ESRI ArcGIS Pro (version 3.4.0 or later).
A preloaded base map, for example, or .
OS NGD API – Features added to an API project in the OS Data Hub with an API Key. See for more information.

Instructions

Set up a connection

Once a new project with a new map has been set up, select Insert > Connections > Server > New OGC API Server.

Add an API URL and set up custom parameters

In the Add OGC API Server Connection dialog:

Server URL: Enter the URL for OS NGD API – Features, excluding the API Key. For example, https://api.os.uk/features/ngd/ofa/v1.

Select Custom request parameters and enter the following:
- Parameter: key
- Value: [Insert your OS API Key here]
Click OK.

Adding layers to the map

You can explore the available layers in OS NGD API – Features by using the ArcGIS Pro Catalog panel.

In the Catalog panel:

To add a layer to the map: Right-click on a layer and select Add to Current Map.

In the pop-up Add OGC API Layer(s) dialog:

Set the maximum features returned: Set the maximum number of features to be displayed (we suggest 1000).
To specify the extent:
- Select the Use Spatial Extent checkbox.
- Get extent from: Select Current visible extent.
- Click OK to load the features onto the map.

The layer will then display in the Contents panel and the data will display on the map:

Adjusting the map view

Features will not automatically refresh when you zoom or pan on the map. This is purposely designed to protect the API from unnecessary spikes in usage.

If the extent of the screen changes and you need to update the features displayed, right-click on the layer in the Contents panel, then select the OGC Features property for the layer, re-click Current visible extent, and click Apply and OK. This will force ESRI ArcGIS Pro to send a new request to the API and load features based on the new extent.

QGIS

Accessing OS NGD data with OS NGD API – Features via QGIS

QGIS is an open GIS (Geospatial Information System) desktop application that allows you to display, interrogate, visualise and create geospatial information including from geo-centric APIs (for example, a WFS).

The instructions that follow demonstrate how to connect to OS NGD API – Features using QGIS.

What you need

QGIS (version 3.12.0 or later).
A preloaded basemap, for example, or .
OS NGD API – Features added to an API project in the OS Data Hub with an API Key. See for more information.

Instructions

Set up a new connection

Once a new project with a base map map has been set up, zoom in to a small area to reduce the number of requests that are initially sent to the API. Select Layer > Add Layer > Add WFS / OGC API - Features Layer.

Create a new connection

In the Data Source Manager | WFS / OGC API - Features dialog click New and in the New WFS Connection dialog:

Name: Provide a name for the connection. You can reuse this connection in the future.
URL: Copy the OS NGD API – Features endpoint address from the OS Data Hub and paste it into this field. Your API Key is automatically appended to this URL in the key parameter.
Authentication: Leave these settings at their defaults. You do not need a username or password as authentication is done through your API Key.
Version: Click Detect to identify the version.
Enable feature paging: Select this option, if necessary.
Page size: Enter a maximum page size. This limits the page size to a maximum number of features. We recommend a setting of about 100 to speed up response times. Larger values may result in a very slow response time.
Other: Leave the other settings at their defaults.
Click OK.

Adding layers to the map

Data Source Manager | WFS / OGC API - Features dialog:

Select your new connection in the dropdown, if necessary.
Click Connect.

When you click Connect, a list of layers available in OS NGD API – Features populates in the main box:

To add a layer to the map: Select the layer to highlight it. You can select multiple layers by using the Ctrl key.

As best practice, only load layers that relate to your current task – not all layers. The more features you call, the longer it takes to load them into QGIS. In addition, each feature, regardless of its layer, counts towards your .

Only request features overlapping the view extent: Select this option.
Click Add.

The layer will then display in the Layers panel and the data will display on the map:

Libraries

Accessing OS NGD data with OS NGD API – Features via web mapping libraries

The following sub-sections provide step-by-step instructions on how to access OS NGD data via OS NGD API – Features in various web mapping libraries:

Leaflet

Accessing OS NGD API – Features via Leaflet

is an open-source JavaScript library for displaying interactive maps on the web or mobile. A simple and lightweight library that will enable you to display and visualise location data and build dynamic applications.

What you'll need

OS Maps API and OS NGD API – Features added to an API project in the OS Data Hub with an API Key. See for more information.
A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files.

Set up your HTML file

Create a new HTML file with a text editor (for example, Notepad, Visual Studio Code).
Add the basic HTML structure to your file with a placeholder <div> for the map.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>OS NGD API – Features | Template (EPSG:3857) | Leaflet</title>
    
    <!--Add the Ordnance Survey Styling-->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/OrdnanceSurvey/os-api-branding@0.3.1/os-api-branding.css" />
    <script src="https://cdn.jsdelivr.net/gh/OrdnanceSurvey/os-api-branding@0.3.1/os-api-branding.js"></script>
    
    <!--Add the Leaflet libraries-->
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
    <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
    
   
    <style>
        /* Set the map container size and style */
        body { margin: 0; padding: 0; }
        #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    
    <!--Create a div element to hold the map-->
    <div id="map"></div>
    
    <!--Add your Javascript code below--> 
    <script>
        // Your Javascript code will go here

    </script>

</body>
</html>

Insert your API Key and OS NGD collection

To enable access to OS APIs an API Key is required. Inside the <script> tag, add a variable called apiKey, replacing 'INSERT_API_KEY_HERE' with the API Key from your project.
Add a variable called collectionID, replacing 'INSERT_COLLECTIONID_HERE' with the collection ID for the desired OS NGD feature type and version (for example, bld-fts-buildingpart-1).

// Set API Key 
 const apiKey = 'INSERT_API_KEY_HERE';
 
 const collectionId= 'INSERT_COLLECTIONID_HERE';

Add a basemap

Define the configuration options for the map, defining minZoom, maxZoom, center, zoom, maxBounds, attributionControl.
- minZoom and maxZoom: Sets the minimum and maximum zoom level for the map. Users will not be able to go beyond these levels.
- center: Sets the initial centre point of the map.
- zoom: Sets the initial zoom level of the map.
- maxBounds: Defines the maximum bounds and restricts panning the map.
- style: Defines the style of the map, configured via a URL pointing at the style specified.
- attributionControl: When set to 'false', it hides the attribution control which displays map credits.
Initialize the map with the id of the <div> element and the configuration option defined in mapOptions.
Using the 'L.tileLayer' method, specify the basemap layer for OS Maps API, which includes your API Key to load the tiles to your map.

// Initialize the map.
    const mapOptions = {
        minZoom: 7,
        maxZoom: 20,
        center: [ 50.727589, -3.541809 ],
        zoom: 18,
        maxBounds: [
            [ 49.528423, -10.76418 ],
            [ 61.331151, 1.9134116 ]
        ],
        attributionControl: false
    };

    const map = L.map('map', mapOptions);

    // Load and display ZXY tile layer on the map.
    const basemap = L.tileLayer(`https://api.os.uk/maps/raster/v1/zxy/Light_3857/{z}/{x}/{y}.png?key=${apiKey}`, {
        maxZoom: 20
    }).addTo(map);

Add an OS NGD API – Features layer

Create a function called fetchFeatures that fetches the API based on the current map extent (bounding box) by generating a bbox string.
Construct the API request URL to fetch OS NGD data from OS NGD API – Features. The URL includes the collectionId, bbox and apiKey.
Once the features have been returned in JSON, update the source data of the map's layers to display the features.

// Add layer group to make it easier to add or remove layers from the map.
    const lyrGroup = new L.layerGroup().addTo(map);

// Define an asynchronous function to fetch and display the NGD Features API features.
    async function fetchFeatures(bounds) {
        // Generate a BBOX string for the map extent.
        const bbox = bounds.toBBoxString();

        // Construct the NGD Features API request URL.
        const url = `https://api.os.uk/features/ngd/ofa/v1/collections/${collectionId}/items?key=${apiKey}&bbox=${bbox}`;

        // Fetch features from the API endpoint.
        const features = await fetch(url).then(response => response.json());

        // Parse the GeoJSON data and display it on the map.
        lyrGroup.clearLayers().addLayer(L.geoJSON(features));
    }

// Get the visible map bounds (BBOX).
    let bounds = map.getBounds();

// Initial fetch and display of features.
    fetchFeatures(bounds);

Load and update features on the map dynamically

The map.on('moveend',...) event handler fetches and updates the features based on the map's current extent.

// Add event which will be triggered when the map has finshed moving (pan + zoom).
// Implements a simple strategy to only request data when the map viewport invalidates
// certain bounds.
    map.on('moveend', function() {
        let bounds1 = new L.latLngBounds(bounds.getSouthWest(), bounds.getNorthEast()),
            bounds2 = map.getBounds();

        if( JSON.stringify(bounds) !== JSON.stringify(bounds1.extend(bounds2)) ) {
            bounds = bounds2;
            fetchFeatures(bounds);
        }
    });

Features within the viewport extent will load initially (first 100 features) and will continue to load as you pan and zoom across the map.

What's next?

Congratulations! You've successfully created a map using Leaflet and added an OS NGD layer using OS NGD API – Features in a few steps.

Now you can continue to explore Ordnance Survey's to learn more about advanced features and functionality, such as adding markers, pop-ups, and additional layers.

MapLibre GL JS

Accessing OS NGD API – Features via MapLibre GL JS

is a free and powerful JavaScript library for displaying interactive maps on the web. It's based on Mapbox GL JS and provides a wide range of features for creating maps with custom styles, markers and interactivity.

What you'll need

OS Maps API and OS NGD API – Features added to an API project in the OS Data Hub with an API Key. See for more information.
A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files.

Set up your HTML file

Create a new HTML file with a text editor (for example, Notepad, Visual Studio Code).
Add the basic HTML structure to your file with a placeholder <div> for the map.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>OS NGD API – Features | Template (EPSG:3857) | Maplibre GL JS</title>
    
    <!--Add the Ordnance Survey Styling-->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/OrdnanceSurvey/os-api-branding@0.3.1/os-api-branding.css" />
    <script src="https://cdn.jsdelivr.net/gh/OrdnanceSurvey/os-api-branding@0.3.1/os-api-branding.js"></script>
    
    <!--Add the Maplibre GL JSlibraries-->
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" />
    <script src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
   
    <style>
        /* Set the map container size and style */
        body { margin: 0; padding: 0; }
        #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    
    <!--Create a div element to hold the map-->
    <div id="map"></div>
    
    <!--Add your Javascript code below--> 
    <script>
        // Your Javascript code will go here

    </script>

</body>
</html>

Insert your API Key and OS NGD collection

To enable access to OS APIs an API Key is required. Inside the <script> tag, add a variable called apiKey, replacing 'INSERT_API_KEY_HERE' with the API Key from your project.
Add a variable called collectionId, replacing 'INSERT_COLLECTIONID_HERE' with the collection ID for the desired OS NGD feature type and version (for example, bld-fts-buildingpart-1).

// Set API Key 
 const apiKey = 'INSERT_API_KEY_HERE';
 
 const collectionId= 'INSERT_COLLECTIONID_HERE';

Add a basemap

To add the OS Maps API, you will need to define the map style using MapLibre GL JS's format. This specifies the source of map tiles, which will be retrieved from OS Maps API in the 'Light' raster tiles style.
Initialise the map object using the maplibregl.Map class to configure the basemap layer and define its properties – container, minZoom, maxZoom, maxBounds, style, center and zoom.
Add navigation controls to the map, excluding the compass button and disabling map rotation.

// Create a map style object using the ZXY service.
    const style = {
    "version": 8,
        "sources": {
            "raster-tiles": {
            "type": "raster",
            "tiles": [`https://api.os.uk/maps/raster/v1/zxy/Light_3857/{z}/{x}/{y}.png?key=${apiKey}`],
            "tileSize": 256
            }
         },
         "layers": [{
             "id": "os-maps-zxy",
             "type": "raster",
             "source": "raster-tiles"
         }]
     };
     
     // Initialize the map object.
         const map = new maplibregl.Map({
             container: 'map',
             minZoom: 6,
             maxZoom: 19,
             style: style,
             maxBounds: [
                 [-10.76418, 49.528423],
                 [1.9134116, 61.331151]
             ],
             center: [-3.541809, 50.727589],
             zoom: 17
         });
         
         map.dragRotate.disable(); // Disable map rotation using right click + drag.
         map.touchZoomRotate.disableRotation(); // Disable map rotation using touch rotation gesture.
         
         // Add navigation control (excluding compass button) to the map.
         map.addControl(new maplibregl.NavigationControl({
             showCompass: false
             }));

The above code creates the main map instance using the MapLibre GL JS library where you can specify various properties:

container: Defines where the map should be displayed. In this instance, it is set to the id of the <div> element.
minZoom and maxZoom: Sets the minimum and maximum zoom level for the map. Users will not be able to go beyond these levels.
maxBounds: Defines the maximum bounds and restricts panning the map.
style: Defines the style of the map, configured via a URL pointing at the style specified.
center: Sets the initial centre point of the map.
zoom: Sets the initial zoom level of the map.

Add an OS NGD API – Features layer

Create an empty GeoJSON placeholder to hold the feature objects called by OS NGD API – Features.
Create a function called fetchFeatures that fetches the API based on the current map extent (bounding box) by generating a bbox string.
Construct the API request URL to fetch OS NGD data from OS NGD API – Features. The URL includes the collectionId, bbox and apiKey.
Once the features have been returned in JSON, update the source data of the map's layers to display the features.

let layers = [ 'polygon', 'linestring', 'point' ];

// Create an empty GeoJSON FeatureCollection.
const geoJson = {
    "type": "FeatureCollection",
    "features": []
};

// Define an asynchronous function to fetch and display the NGD Features API features.
async function fetchFeatures(bounds) {
        // Generate a BBOX string for the map extent.
        const bbox = bounds.toArray().toString();

        // Construct the NGD Features API request URL.
        const url = `https://api.os.uk/features/ngd/ofa/v1/collections/${collectionId}/items?&key=${apiKey}&bbox=${bbox}`;

        // Fetch features from the API endpoint.
        const features = await fetch(url).then(response => response.json());

        // Update the source data with the new GeoJSON data.
        layers.forEach((element) => map.getSource(element).setData(features))
}

Load and update features on the map dynamically

Event listeners are triggered when the map loads and finishes moving (panning or zooming) to load and update features based on the map's updated extent. Inside the map.on('load',...) event handler, we add styles for various types of features, including polygons, linestrings and points so that any collectionId specified will render.

The map.on('moveend',...) event handler will then fetch and update the features based on the map's current extent.

map.on('load', () => {
    // Add a fill style layer to render polygons on the map.
    map.addLayer({
        "id": "polygon",
        "type": "fill",
        "source": {
            "type": "geojson",
            "data": geoJson
        },
        "layout": {},
        "paint": {
            "fill-color": "rgba(51,136,255,0.3)",
            "fill-outline-color": "#38f"
        },
        "filter": [ "==", "$type", "Polygon" ]
    });

    // Add a line style layer to render linestrings on the map.
    map.addLayer({
        "id": "linestring",
        "type": "line",
        "source": {
            "type": "geojson",
            "data": geoJson
        },
        "layout": {},
        "paint": {
            "line-color": "#38f",
            "line-width": 1
        },
        "filter": [ "==", "$type", "LineString" ]
    });

    // Add a circle style layer to render points on the map.
    map.addLayer({
        "id": "point",
        "type": "circle",
        "source": {
            "type": "geojson",
            "data": geoJson
        },
        "layout": {},
        "paint": {
            "circle-color": "rgba(51,136,255,0.8)",
            "circle-radius": 4,
            "circle-stroke-color": "#fff",
            "circle-stroke-width": 1
        },
        "filter": ["==", "$type", "Point"]
    });

    // Get the visible map bounds (BBOX).
    let bounds = map.getBounds();

    // Initial fetch and display of features.
    fetchFeatures(bounds);
        
    // Add event which will be triggered when the map has finshed moving (pan + zoom).
    // Implements a simple strategy to only request data when the map viewport invalidates
    // certain bounds.
    map.on('moveend', function() {
        let bounds1 = new maplibregl.LngLatBounds(bounds.getSouthWest(), bounds.getNorthEast()),
            bounds2 = map.getBounds();

        if( JSON.stringify(bounds) !== JSON.stringify(bounds1.extend(bounds2)) ) {
            bounds = bounds2;
            fetchFeatures(bounds);
        }
    });
});

Features within the viewport extent will load initially (first 100 features) and will continue to load as you pan and zoom across the map.

What's next?

Congratulations! You've successfully created a map using MapLibre GL JS and added an OS NGD layer using OS NGD API – Features in a few steps.

Now you can continue to explore Ordnance Survey's to learn more about advanced features and functionality, such as adding markers, pop-ups, and additional layers.

OpenLayers

Accessing OS NGD API – Features via OpenLayers

is a free and open-source JavaScript library for displaying interactive maps on the web. It is a powerful tool that can be used to create a wide variety of map-based applications, from simple web maps to complex GIS applications.

OpenLayers is easy to use and can be integrated with a variety of other web development frameworks.

What you'll need

OS Maps API and OS NGD API – Features added to an API project in the OS Data Hub with an API Key. See for more information.
A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files.

Set up your HTML file

Create a new HTML file with a text editor (for example, Notepad, Visual Studio Code).
Add the basic HTML structure to your file with a placeholder <div> for the map.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>OS NGD API – Features | Template (EPSG:3857) | OpenLayers</title>
    
    <!--Add the Ordnance Survey Styling-->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/OrdnanceSurvey/os-api-branding@0.3.1/os-api-branding.css" />
    <script src="https://cdn.jsdelivr.net/gh/OrdnanceSurvey/os-api-branding@0.3.1/os-api-branding.js"></script>
    
    <!--Add the OpenLayers libraries-->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@v8.1.0/ol.css" />
    <script src="https://cdn.jsdelivr.net/npm/ol@v8.1.0/dist/ol.js"></script>
    
    <style>
        /* Set the map container size and style */
        body { margin: 0; padding: 0; }
        #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    
    <!--Create a div element to hold the map-->
    <div id="map"></div>
    
    <!--Add your Javascript code below--> 
    <script>
        // Your Javascript code will go here

    </script>

</body>
</html>

Insert your API Key and OS NGD collection

To enable access to OS APIs an API Key is required. Inside the <script> tag, add a variable called apiKey, replacing 'INSERT_API_KEY_HERE' with the API Key from your project.
Add a variable called collectionId, replacing 'INSERT_COLLECTIONID_HERE' with the collection ID for the desired OS NGD feature type and version (for example, bld-fts-buildingpart-1).

// Set API Key 
 const apiKey = 'INSERT_API_KEY_HERE';
 
 const collectionId= 'INSERT_COLLECTIONID_HERE';

Add a basemap

Create a source for the basemap layer using OS Maps API and initialise the ol.map class with the applicable map properties – target, layers and view. Add the following code inside the JavaScript block:

// Initialize the map object.
    const map = new ol.Map({
        target: 'map',
        layers: [
            new ol.layer.Tile({
                source: new ol.source.XYZ({
                    url: `https://api.os.uk/maps/raster/v1/zxy/Light_3857/{z}/{x}/{y}.png?key=${apiKey}`
                })
            })
        ],
        view: new ol.View({
            projection: 'EPSG:3857',
            extent: ol.proj.transformExtent([ -10.76418, 49.528423, 1.9134116, 61.331151 ], 'EPSG:4326', 'EPSG:3857'),
            minZoom: 7,
            maxZoom: 20,
            center: ol.proj.fromLonLat([ -3.541809, 50.727589 ]),
            zoom: 18
        })
    });

The above code creates the main map instance using the OpenLayers library where you can specify various properties:

target: Defines where the map should be displayed. In this instance, it is set to the id of the <div> element.
layers: An array containing the layers to be added to the map.
view: Defines the initial view of the main, containing various settings such as projection, extent (the geographic bounds of the map), minimum and maximum zoom levels, centre of the map and the initial zoom level.

Add an OS NGD API – Features layer

Define and initialise the source using the ol.source.Vector class to make a request to OS NGD API – Features. By utilising the ol.loadingstrategy.bbox this means that data from OS NGD API – Features will be loaded based on the visible map extent.
To create a separate layer to overlay OS NGD data onto the map, you will need to add the ngdFeatures layers to the ol.map object to render both layers on the map.

// Create the NGD Features API layer (with BBOX strategy).
    const ngdFeatures = new ol.layer.Vector({
        source: new ol.source.Vector({
            format: new ol.format.GeoJSON(),
            url: function(extent) {
                return (
                    `https://api.os.uk/features/ngd/ofa/v1/collections/${collectionId}/items?key=${apiKey}&bbox=${extent.join(',')}&bbox-crs=http://www.opengis.net/def/crs/EPSG/0/3857`
                );
            },
            strategy: ol.loadingstrategy.bbox
        })
    });

    // Add the NGD Features API layer to the map.
    map.addLayer(ngdFeatures);

Features within the viewport extent will load initially (first 100 features) and will continue to load as you pan across the map.

What's next?

Congratulations! You've successfully created a map using OpenLayers and added an OS NGD layer using OS NGD API – Features in a few steps.

Now you can continue to explore Ordnance Survey's to learn more about advanced features and functionality, such as adding markers, pop-ups, and additional layers.

Python (Geopandas)

Accessing OS NGD API – Features via Python (Geopandas)

This example will provide an introduction on how to use OS NGD API – Features to extract and plot OS NGD data! We’ll be using GeoPandas, a library that builds on Pandas to help manage and analyse spatial data.

What you'll need

OS NGD API – Features added to an API project in the OS Data Hub with an API Key. See for more information.
The following dependencies installed:

More examples in an executable notebook format are available through our OS APIs Python wrapper.

Import the required libraries

import requests
import geopandas as gpd
from shapely.geometry import shape

Set up your OS API credentials

# OS NGD API - Features API Key
api_key = "INSERT_API_KEY"

# OS NGD API - Features base URL
base_url = "https://api.os.uk/features/ngd/ofa/v1"

# OS NGD API - Features CollectionId
collection= "wtr-fts-water-2"

Request data from OS NGD API - Features

# Define your bounding box
bbox = [-314177.76517933805,6641680.87433119,-304909.7754997604,6653318.411887609] # Example: Glastonbury Canal

# Initialize an empty list to collect all features
all_features = []

# Loop through 20 pages
for page in range(20):
 offset = page * 100  # Calculate the offset based on the page number
 params = {
        "key": api_key,
        "bbox": ",".join(map(str, bbox)),
        "limit": 100,
        "offset": offset,
        "bbox-crs": "http://www.opengis.net/def/crs/EPSG/0/3857",
        "crs": "http://www.opengis.net/def/crs/EPSG/0/3857",
 }
 
 # Send a request to the OS NGD API - Features
 response = requests.get(f"{base_url}/collections/{collection}/items", params=params)
 
 # Check if the request was successful
 if response.status_code == 200:
   data = response.json()
   features = data.get("features", [])
   all_features.extend(features)
   if len(features) < params["limit"]:  # Stop as there are no more features to retrieve 
     break
 else:
   print(f"Error: {response.status_code}")
   break  # Stop the loop in case of an error

Load data into a GeoPandas DataFrame

# Extract the geometries and attributes for each feature
geometry = [shape(feature["geometry"]) for feature in all_features]
attributes = [feature["properties"] for feature in all_features]

# Create a GeoDataFrame from the geometries and attributes
gdf = gpd.GeoDataFrame(attributes, geometry=geometry)

# Set the CRS of the GeoDataFrame to EPSG:3857 (Web Mercator)
gdf.set_crs("EPSG:3857", inplace=True)

Plot Data

# Plot the features
gdf.plot(figsize=(12,8),facecolor="#2d8fb6", edgecolor="#b19d3e", lw=0.05)

OS NGD API – Tiles

What is OS NGD API – Tiles?

OS NGD API – Tiles offers you a vector tile service powered by the OS NGD. It provides a detailed and customisable basemap that's based on the latest OGC API – Tiles standard to help you create stunning and interactive web maps. It can be used with most web mapping libraries, including OpenLayers, MapLibre GL JS and Leaflet. The major benefit of vector tiles is that they are optimised for use across the internet and are therefore great for building interactive web maps that allow users to zoom, pan, rotate, tilt and more.

You have a choice between using Ordnance Survey styles or creating your own. You can customise the content and style to create a professional-looking map that perfectly meets your needs, matches your branding, and pleases your customers.

OS NGD API – Tiles is available in two projections: British National Grid for Great Britain (GB) data and Web Mercator, a global coordinate system.

Benefits

Things to remember for OS NGD API – Tiles

You can:

Use it as a basemap in GIS, web or mobile applications.
View the whole of Great Britain in unrivalled detail.
Seamlessly pan, zoom, pitch and tilt the map.
Overlay your own data on the basemap to give geographic context to your data.
Trace over OS NGD (Premium Data) detailed geometries.
Customise the map style and content to create the map you need.
Access maps in different projections: British National Grid and Web Mercator.

You can't:

Retrieve all the detailed attribution from OS NGD data.
Access data from the:
- OS NGD Address Theme
- OS NGD Routing and Asset Management Information (RAMI) Collection (of the OS NGD Transport Theme)

What data is available?

What feature types are available in OS NGD API – Tiles?

Basemap (ngd-base)

The following table details the OS NGD datasets that were used to create the OS NGD API – Tiles basemap. The result is a detailed OS basemap that combines and OS NGD data.

Theme

Collection

Feature Type(s)

Find out more about the hierarchy of OS NGD data .

Data overlays

The following table details the OS NGD datasets that can be used as overlays to the basemap to add additional information:

Attribution available in OS NGD API – Tiles

The following attribution is available as part of OS NGD API – Tiles:

The map features do not contain every OS NGD feature type, nor the complete list of attribution available within the feature types that are included; we have purposefully only selected feature types and a subset of attribution from them that are useful for visualisation as this keeps the tiles lightweight and quick to render.

Update frequency

Technical Specification

OS NGD API – Tiles Technical Specification provides an overview of the endpoints available, as well as the parameters that can be used with each endpoint. The Technical Specification is intended to be used by customers who want to integrate with the API. Click into each endpoint to learn more.

Getting Started

The following pages provide an overview of how to get started using the OS NGD API – Tiles. They cover the core elements to get started in the most common and .

These pages should be used in conjunction with the more detailed pages within the and .

GIS Software

Accessing OS NGD data with OS NGD API – Tiles via GIS software

The following sub-sections provide step-by-step instructions on how to access OS NGD data via OS NGD API – Tiles in various GIS software packages:

Cadcorp SIS

Accessing OS NGD data with OS NGD API – Tiles via Cadcorp SIS

The Cadcorp Spatial Information System® (Cadcorp SIS®) is an integrated family of geospatial products comprising desktop, web, and developer applications.

Cadcorp SIS Desktop connects directly to the OS Data Hub through dedicated wizards.

What you need

Cadcorp SIS (version SIS 9.1 or later).
OS NGD API – Tiles added to an API project in the OS Data Hub with an API Key. See for more information.

Instructions

These instructions are based on Cadcorp SIS Desktop version 9.1.2109.64.

Add overlay

Once a new map has been set up, in the Home tab, click Add Overlay.

Select API

In the Overlay Types dialog:

Select Ordnance Survey (GB) > OS (GB) Data Hub, and then click Next.

In the OS (GB) Data Hub dialog:

Select OS National Geographic Database (NGD) API – Tiles.
API Key: Enter your API key.
Premium/Public Sector Plan: Select this option if you have this plan.
Save in the UI settings database (encrypted): Select this option.
Click Next.

Adding layers to the map

In the OS (GB) Data Hub NGD API - Tiles dialog, select the appropriate layer from the list of available options, and then click Finish.

The selected layer will then display in the SIS Workspace Definition (SWD) and the data will display in the map area:

QGIS

Accessing OS NGD data with OS NGD API – Tiles via QGIS

The instructions that follow demonstrate how to connect to OS NGD API – Tiles using QGIS.

What you'll need

QGIS (version 3.22.0 or later).
OS NGD API – Tiles added to an API project in the OS Data Hub with an API Key. See Getting started with an API project for more information.

Instructions

Set up a new connection

Once a new project with a base map map has been set up, select Layer > Add Layer > Add Vector Tile Layer.

Create a new connection

In the Data Source Manager | Vector Tile dialog:

Click New
Select New Generic Connection...

In the Data Source Manager | Vector Tile dialog:

Name: Provide a name for the connection.
URL: Input the Retrieve Tile request URL for the OS NGD API – Tiles collection.
Min. and Max. Zoom Levels: Set these as follows based on your preferred projection:
- Web Mercator (EPSG: 3857): Min Zoom = 6; Max Zoom = 19
- British National Grid (BNG: EPSG: 27700): Min Zoom = 0; Max Zoom = 15
Style URL: Input the Retrieve Style request URL for the OS NGD API – Tiles collection.
Authentication: Leave these settings at their defaults.
Other: Leave all other settings at their defaults.
Click OK.

To retrieve tiles and style them appropriately, you will need two URLs. The URLs have slight variations based on the collection ID and projection.

Here are some example URLs to retrieve the basemap (ngd-base) in Web Mercator (EPSG: 3857):

https://api.os.uk/maps/vector/ngd/ota/v1/collections/ngd-base/tiles/3857/{z}/{y}/{x}?key={INSERT_YOUR_API_KEY}
https://api.os.uk/maps/vector/ngd/ota/v1/collections/ngd-base/styles/3857?key={INSERT_YOUR_API_KEY}

To learn more about the available collections in OS NGD API – Tiles, you can view what data is available .

Please note: You will need to replace the /{tileMatrix}/{tileRow}/{tileCol} used in the default 'retrieve tile' URL with /{z}/{y}/{x} to be able to connect to OS NGD API – Tiles.

Add layer

Navigate to Layer > Data Source Manager > Vector Tile.

In the Data Source Manager | Vector Tile dialog:

Select your new connection to OS NGD API – Tiles
Click Add.

The layer will then display in the Layers panel and the data will display on the map:

Libraries

Accessing OS NGD data with OS NGD API – Tiles via web mapping libraries

The following sub-sections provide step-by-step instructions on how to access OS NGD data via OS NGD API – Tiles in various web mapping libraries:

Leaflet

Accessing OS NGD API – Tiles via Leaflet

What you'll need

OS NGD API – Tiles added to an API project in the OS Data Hub with an API Key. See for more information.
A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files.

Set up your HTML file

Create a new HTML file with a text editor (for example, Notepad, Visual Studio Code).
Add the basic HTML structure to your file with a placeholder <div> for the map.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>OS NGD API – Tiles | Template (EPSG:3857) | Leaflet</title>
    
    <!--Add the Ordnance Survey Styling-->
    <link rel="stylesheet" href="https://labs.os.uk/public/os-api-branding/v0.3.1/os-api-branding.css" />
    <script src="https://labs.os.uk/public/os-api-branding/v0.3.1/os-api-branding.js"></script>
    
    <!--Add the Leaflet libraries-->
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.3/dist/leaflet.css" />
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" />
    <script src="https://unpkg.com/leaflet@1.9.3/dist/leaflet.js"></script>
    <script src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
    <script src="https://unpkg.com/@maplibre/maplibre-gl-leaflet@0.0.19/leaflet-maplibre-gl.js"></script>
    
    <style>
        /* Set the map container size and style */
        body { margin: 0; padding: 0; }
        #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    
    <!--Create a div element to hold the map-->
    <div id="map"></div>
    
    <!--Add your Javascript code below--> 
    <script>
        // Your Javascript code will go here

    </script>

</body>
</html>

Insert your API Key

To enable access to OS APIs an API Key is required. Inside the <script> tag, add a variable called apiKey, replacing 'INSERT_API_KEY_HERE' with the API Key from your project.
Inside the <script> tag, add another variable called collectionIdwith the collection ID for the OS NGD API – Tiles basemap – ngd-base.

// Set API Key and collection ID
 const apiKey = 'INSERT_API_KEY_HERE';
 
 const collectionId = 'ngd-base';

Adding a fetch and response interceptor

We need to intercept and customise the style request, adding a tiles property to provide a correctly formatted URL and ensure authentication through the apiKey is enabled to make sure that the correct tiles are requested.
Add the following code inside the JavaScript block:

// Modify the JSON style request incorporate a `tiles` property which lists an array of tile endpoints.
// The '&key=' HTTP query parameter is also appended to each tile endpoint to authenticate the request.
// NOTE: The {z}, {x} and {y} template values are replaced with the corresponding integers at runtime.
    const { fetch: originalFetch } = window;
    window.fetch = async (...args) => {
        let [ resource, config ] = args;

        let response = await originalFetch(resource, config);
        if( response.url != `https://api.os.uk/maps/vector/ngd/ota/v1/collections/${collectionId}/styles/3857` )
            return response;

        // Response interceptor.
        const json = () =>
            response.clone().json().then((data) => {
                delete data.sources[ collectionId ].url;
                data.sources[ collectionId ].tiles = [ `https://api.os.uk/maps/vector/ngd/ota/v1/collections/${collectionId}/tiles/3857/{z}/{y}/{x}?key=${apiKey}` ];
                return data;
            });

        response.json = json;
        return response;
    };

Create a map and map view

Initialize the map object using the L.Map class to configure the vector tile layer and the mapOptions variable to define its properties – minZoom, maxZoom, maxBounds, center and zoom.

// Initialize the map.
    const mapOptions = {
        minZoom: 7,
        maxZoom: 20,
        center: [ 50.727589, -3.541809 ],
        zoom: 18,
        maxBounds: [
            [ 49.528423, -10.76418 ],
            [ 61.331151, 1.9134116 ]
        ],
        attributionControl: false
    };

    const map = L.map('map', mapOptions);

    // Load and display vector tile layer on the map.
    const gl = L.maplibreGL({
        style: `https://api.os.uk/maps/vector/ngd/ota/v1/collections/${collectionId}/styles/3857`
    }).addTo(map);

The above code creates the main map instance using the Leaflet library where you can specify various properties:

minZoom and maxZoom: Sets the minimum and maximum zoom level for the map. Users will not be able to go beyond these levels.
maxBounds: Defines the maximum bounds and restricts panning the map.
center: Sets the initial centre point of the map.
zoom: Sets the initial zoom level of the map.

What's next?

Congratulations! You've successfully created a vector map using Leaflet using OS NGD API – Tiles in a few steps.

Now you can continue to explore Ordnance Survey's to learn more about advanced features and functionality, such as adding markers, pop-ups, and additional layers.

MapLibre GL JS

Accessing OS NGD API – Tiles via MapLibre GL JS

What you'll need

OS NGD API – Tiles added to an API project in the OS Data Hub with an API Key. See for more information.
A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files.

Set up your HTML file

Create a new HTML file with a text editor (for example, Notepad, Visual Studio Code).
Add the basic HTML structure to your file with a placeholder <div> for the map.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>OS NGD API – Tiles | Template (EPSG:3857) | MapLibre GL JS</title>
    
    <!--Add the Ordnance Survey Styling-->
    <link rel="stylesheet" href="https://labs.os.uk/public/os-api-branding/v0.3.1/os-api-branding.css" />
    <script src="https://labs.os.uk/public/os-api-branding/v0.3.1/os-api-branding.js"></script>
    
    <!--Add the MapLibre GL JS libaries -->
     <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" />
    <script src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
    
    <style>
        /* Set the map container size and style */
        body { margin: 0; padding: 0; }
        #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    
    <!--Create a div element to hold the map-->
    <div id="map"></div>
    
    <!--Add your Javascript code below--> 
    <script>
        // Your Javascript code will go here

    </script>

</body>
</html>

Insert your API Key

To enable access to OS APIs an API Key is required. Inside the <script> tag, add a variable called apiKey, replacing 'INSERT_API_KEY_HERE' with the API Key from your project.
Inside the <script> tag, add another variable called collectionId with the collection ID for the OS NGD API – Tiles basemap – ngd-base.

// Set API Key and collection ID
 const apiKey = 'INSERT_API_KEY_HERE';
 
 const collectionId = 'ngd-base';

Adding a fetch and response interceptor

We need to intercept and customise the style request, adding a tiles property to provide a correctly formatted URL and ensuring authentication through the apiKey is enabled to make sure that the correct tiles are requested.
Add the following code inside the JavaScript block:

// Modify the JSON style request incorporate a `tiles` property which lists an array of tile endpoints.
// The '&key=' HTTP query parameter is also appended to each tile endpoint to authenticate the request.
// NOTE: The {z}, {x} and {y} template values are replaced with the corresponding integers at runtime.
    
    const { fetch: originalFetch } = window;
    window.fetch = async (...args) => {
        let [ resource, config ] = args;

        let response = await originalFetch(resource, config);
        if( response.url != `https://api.os.uk/maps/vector/ngd/ota/v1/collections/${collectionId}/styles/3857` )
            return response;

        // Response interceptor.
        const json = () =>
            response.clone().json().then((data) => {
                data.sources[ collectionId ].tiles = [ `${data.sources[ collectionId ].url}/{z}/{y}/{x}?key=${apiKey}` ];
                delete data.sources[ collectionId ].url;
                return data;
            });

        response.json = json;
        return response;
    };

Create a map and map view

Initialise the map object using the maplibregl.Map class to configure the vector tile layer and define its properties – container, minZoom, maxZoom, maxBounds, style, center and zoom.
Add navigation controls to the map, excluding the compass button and disabling map rotation.

// Initialize the map object.
    const map = new maplibregl.Map({
        container: 'map',
        minZoom: 6,
        maxZoom: 19,
        maxBounds: [ [ -8.74, 49.84 ], [ 1.96, 60.9 ] ],
        style: `https://api.os.uk/maps/vector/ngd/ota/v1/collections/${collectionId}/styles/3857`,
        center: [ -3.541809, 50.727589 ],
        zoom: 17,
        attributionControl: false
    });

    map.dragRotate.disable(); // Disable map rotation using right click + drag.
    map.touchZoomRotate.disableRotation(); // Disable map rotation using touch rotation gesture.

    // Add navigation control (excluding compass button) to the map.
    map.addControl(new maplibregl.NavigationControl({
        showCompass: false
    }));

The above code creates the main map instance using the MapLibre GL JS library where you can specify various properties:

container: Defines where the map should be displayed. In this instance, it is set to the ID of the <div> element.
minZoom and maxZoom: Sets the minimum and maximum zoom level for the map. Users will not be able to go beyond these levels.
maxBounds: Defines the maximum bounds and restricts panning the map.
style: Defines the style of the map, configured via a URL pointing at the default style for the 'collectionId' defined.
center: Sets the initial centre point of the map.
zoom: Sets the initial zoom level of the map.

What's next?

Congratulations! You've successfully created a vector map using MapLibre GL JS using OS NGD API – Tiles in a few steps.

Now you can continue to explore Ordnance Survey's to learn more about advanced features and functionality, such as adding markers, pop-ups, and additional layers.

OpenLayers

Accessing OS NGD API – Tiles via OpenLayers

OpenLayers is a free and open-source JavaScript library for displaying interactive maps on the web. It is a powerful tool that can be used to create a wide variety of map-based applications, from simple web maps to complex GIS applications.

OpenLayers is easy to use and can be integrated with a variety of other web development frameworks.

What you'll need

OS NGD API – Tiles added to an API project in the OS Data Hub with an API Key. See Getting started with an API project for more information.
A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files.

Set up your HTML file

Create a new HTML file with a text editor (for example, Notepad, Visual Studio Code).
Add the basic HTML structure to your file with a placeholder <div> for the map.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>OS NGD API – Tiles | Template (EPSG:3857) | OpenLayers</title>
    
    <!--Add the Ordnance Survey Styling-->
    <link rel="stylesheet" href="https://labs.os.uk/public/os-api-branding/v0.3.1/os-api-branding.css" />
    <script src="https://labs.os.uk/public/os-api-branding/v0.3.1/os-api-branding.js"></script>
    
    <!--Add the OpenLayers libraries-->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@v7.3.0/ol.css" />
    <script src="https://cdn.jsdelivr.net/npm/ol@v7.3.0/dist/ol.js"></script>
    <script src="https://unpkg.com/ol-mapbox-style@9.7.0/dist/olms.js"></script>
        
    <style>
        /* Set the map container size and style */
        body { margin: 0; padding: 0; }
        #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    
    <!--Create a div element to hold the map-->
    <div id="map"></div>
    
    <!--Add your Javascript code below--> 
    <script>
        // Your Javascript code will go here

    </script>

</body>
</html>

Insert your API Key

To enable access to OS APIs an API Key is required. Inside the <script> tag, add a variable called apiKey, replacing 'INSERT_API_KEY_HERE' with the API Key from your project.
Inside the <script> tag, add another variable called collectionId with the collection ID for the OS NGD API – Tiles basemap – ngd-base.

// Set API Key and collection ID
 const apiKey = 'INSERT_API_KEY_HERE';
 
 const collectionId = 'ngd-base';

Tile grid set up

To correctly render the vector tiles within OpenLayers, you will need to fetch the defined EPSG:3857 Tile Matrix Set and style definitions from the OS NGD API – Tiles service. The two endpoints provide information about the structure of the vector tiles and how the styles are to be applied.
A promise.all is used to process the data to ensure that both requests are completed before proceeding.
Based on the fetched Tile Matrix Set data, a tile grid is defined using the ol.tilegrid.TileGrid class. The tile grid provides information about the resolution, origin and tile sizes to handle the vector tiles correctly.
Add the following code inside the JavaScript block:

// Define the Tile Grid and style

const tmsPromise = fetch('https://api.os.uk/maps/vector/ngd/ota/v1/tilematrixsets/3857').then((response) => response .json());
const glStylePromise = fetch(`https://api.os.uk/maps/vector/ngd/ota/v1/collections/${collectionId}/styles/3857`).then((response) => response .json());

Promise.all([tmsPromise, glStylePromise]).then((values) => {
    const tms = values[0];
    const glStyle = values[1];

    const tilegrid = new ol.tilegrid.TileGrid({
        resolutions: tms.tileMatrices.map(({ cellSize }) => cellSize),
        origin: tms.tileMatrices[0].pointOfOrigin,
        tileSize: [ tms.tileMatrices[0].tileHeight, tms.tileMatrices[0].tileWidth ]
    });

Define a vector tile layer

Define the a new vector tiles layer and source that will be used to fetch vector tiles from OS NGD API – Tiles. The ol.layer.VectorTile uses a ol.source.OGCVectorTile source to retrieve tiles from the API.
After creating the vector layer, you will need to use a style function to ensure that the Ordnance Survey styles are applied to each tile. Use the olms.applyStyle function to retrieve the style sheets available for the basemap.

// Define the vector tile layer.
    const formatMvt = new ol.format.MVT();
    formatMvt.supportedMediaTypes.push('application/octet-stream');

    const vectorTileLayer = new ol.layer.VectorTile({
        source: new ol.source.OGCVectorTile({
            url: `https://api.os.uk/maps/vector/ngd/ota/v1/collections/${collectionId}/tiles/3857?key=${apiKey}`,
            format: formatMvt,
            projection: 'EPSG:3857',
            tileGrid: tilegrid
        }),
        declutter: true
    });

// Apply a style function to the vector tile layer.
    olms.applyStyle(
        vectorTileLayer,
        glStyle,
        collectionId,
        { styleUrl: null } ,
        tilegrid.getResolutions()
    );

Create a map and map view

Initialize the map object using the ol.map class to configure the vector tile layer and define its properties – target, layers and view.

// Initialize the map object.
    const map = new ol.Map({
        layers: [ vectorTileLayer ],
        target: 'map',
        view: new ol.View({
            projection: 'EPSG:3857',
            extent: ol.proj.transformExtent([ -10.76418, 49.528423, 1.9134116, 61.331151 ], 'EPSG:4326', 'EPSG:3857'),
            resolutions: tilegrid.getResolutions(),
            minZoom: 6,
            maxZoom: 19,
            center: ol.proj.fromLonLat([ -3.541809, 50.727589 ]),
            zoom: 17
        })
    });
});

The above code creates the main map instance using the OpenLayers library where you can specify various properties:

target: Defines where the map should be displayed. In this instance it is set to the ID of the <div> element.
layers: An array containing the layers to be added to the map.
view: Defines the initial view of the main, containing various settings such as projection, extent (the geographic bounds of the map), minimum and maximum zoom levels, centre of the map and the initial zoom level.

What's next?

Congratulations! You've successfully created a vector map using OpenLayers using OS NGD API – Tiles in a few steps.

Now you can continue to explore Ordnance Survey's code examples to learn more about advanced features and functionality, such as adding markers, pop-ups, and additional layers.

{ "id": "text", "title": "text", "description": "text", "itemType": "text", "extent": { "spatial": { "crs": "text", "bbox": [ [ 1 ] ] }, "temporal": { "trs": "text", "interval": [ [ "text" ] ] } }, "storageCrs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84", "links": [ { "href": "text", "rel": "text", "type": "text", "title": "text" } ], "crs": [ "http://www.opengis.net/def/crs/OGC/1.3/CRS84" ] }

{ "$schema": "text", "$id": "text", "type": "text", "title": "text", "description": "text", "properties": { "ANY_ADDITIONAL_PROPERTY": { "title": "text", "type": "text", "format": "text", "maxLength": 1, "pattern": "text", "description": "text", "hierarchy": "text", "parent": "text", "child": "text", "minItems": 1, "maxItems": 1, "items": { "title": "text", "type": "text", "format": "text", "maxLength": 1, "pattern": "text", "description": "text", "hierarchy": "text", "parent": "text", "child": "text", "minItems": 1, "maxItems": 1, "items": { "title": "text", "type": "text", "format": "text", "maxLength": 1, "pattern": "text", "description": "text", "hierarchy": "text", "parent": "text", "child": "text", "minItems": 1, "maxItems": 1, "items": { "title": "text", "type": "text", "format": "text", "maxLength": 1, "pattern": "text", "description": "text", "hierarchy": "text", "parent": "text", "child": "text", "minItems": 1, "maxItems": 1, "items": "[Circular Reference]", "enum": [ "text" ] }, "enum": [ "text" ] }, "enum": [ "text" ] }, "enum": [ "text" ] } } }

get

/collections/{collectionId}/items

Authorizations

Path parameters

collectionIdenumrequired

A known collection ID.

Example: bld-fts-building-1

Options: bld-fts-building-1, bld-fts-building-2, bld-fts-building-3, bld-fts-buildingline-1, bld-fts-buildingpart-1, bld-fts-buildingpart-2, gnm-fts-namedarea-1, gnm-fts-namedpoint-1, gnm-fts-namedroadjunction-1, lnd-fts-land-1, lnd-fts-land-2, lnd-fts-land-3, lnd-fts-landform-1, lnd-fts-landformline-1, lnd-fts-landformpoint-1, lnd-fts-landpoint-1, lus-fts-site-1, lus-fts-site-2, lus-fts-siteaccesslocation-1, lus-fts-siteroutingpoint-1, str-fts-compoundstructure-1, str-fts-compoundstructure-2, str-fts-fieldboundary-1, str-fts-structure-1, str-fts-structure-2, str-fts-structure-3, str-fts-structureline-1, str-fts-structurepoint-1, trn-fts-cartographicraildetail-1, trn-fts-rail-1, trn-fts-rail-2, trn-fts-rail-3, trn-fts-roadline-1, trn-fts-roadtrackorpath-1, trn-fts-roadtrackorpath-2, trn-fts-roadtrackorpath-3, trn-ntwk-connectinglink-1, trn-ntwk-connectingnode-1, trn-ntwk-ferrylink-1, trn-ntwk-ferrynode-1, trn-ntwk-ferryterminal-1, trn-ntwk-path-1, trn-ntwk-pathlink-1, trn-ntwk-pathnode-1, trn-ntwk-pavementlink-1, trn-ntwk-railwaylink-1, trn-ntwk-railwaylinkset-1, trn-ntwk-railwaynode-1, trn-ntwk-road-1, trn-ntwk-roadjunction-1, trn-ntwk-roadlink-1, trn-ntwk-roadlink-2, trn-ntwk-roadlink-3, trn-ntwk-roadnode-1, trn-ntwk-street-1, trn-ntwk-tramonroad-1, trn-rami-averageandindicativespeed-1, trn-rami-highwaydedication-1, trn-rami-maintenancearea-1, trn-rami-maintenanceline-1, trn-rami-maintenancepoint-1, trn-rami-reinstatementarea-1, trn-rami-reinstatementline-1, trn-rami-reinstatementpoint-1, trn-rami-restriction-1, trn-rami-routinghazard-1, trn-rami-routingstructure-1, trn-rami-specialdesignationarea-1, trn-rami-specialdesignationline-1, trn-rami-specialdesignationpoint-1, wtr-fts-intertidalline-1, wtr-fts-tidalboundary-1, wtr-fts-water-1, wtr-fts-water-2, wtr-fts-water-3, wtr-fts-waterpoint-1, wtr-ntwk-waterlink-1, wtr-ntwk-waterlinkset-1, wtr-ntwk-waternode-1

Query parameters

bboxnumber[]

The optional bbox parameter specifies a supported bounding box. Only features that have a geometry that intersects the bounding box are selected. The bounding box is provided as four comma-separated numbers: Lower left corner, coordinate axis 1 (e.g. min x axis) Lower left corner, coordinate axis 2 (e.g. min y axis) Upper right corner, coordinate axis 1 (e.g. max x axis) Upper right corner, coordinate axis 2 (e.g. max y axis)The default coordinate reference system of the values is WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate reference system is specified in the parameter bbox-crs.

Example: [-0.183678,51.474968,-0.068321,51.540143]

bbox-crsenum

The coordinate reference system of the bbox parameter. It must be a 2D coordinate reference system supported by the collection. Default is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).

Options: http://www.opengis.net/def/crs/OGC/1.3/CRS84, http://www.opengis.net/def/crs/EPSG/0/27700, http://www.opengis.net/def/crs/EPSG/0/4326, http://www.opengis.net/def/crs/EPSG/0/3857

crsenum

The coordinate reference system of the response geometries. It must be a coordinate reference system supported by the collection. Default is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).

Options: http://www.opengis.net/def/crs/OGC/1.3/CRS84, http://www.opengis.net/def/crs/EPSG/0/27700, http://www.opengis.net/def/crs/EPSG/0/4326, http://www.opengis.net/def/crs/EPSG/0/3857, http://www.opengis.net/def/crs/EPSG/0/7405

datetimestring

Either a local date, a date-time with UTC time zone (Z) or an open or closed interval. Open ranges in time intervals at the start or end are supported using a double-dot (..) or an empty string for the start/end. Date and time expressions adhere to RFC 3339. Examples:A date-time: '2021-12-12T23:20:50Z'A closed interval: '2021-12-12T00:00:00Z/2021-12-18T12:31:12Z'Open intervals: '2021-12-12T00:00:00Z/..' or '../2021-12-18T12:31:12Z'An interval until now: '2018-02-12T00:00:00Z/..' or '2018-02-12T00:00:00Z/'Selects features that have a temporal property that intersects the value of the parameter.

Example: 2018-02-12T00:00:00Z/..

limitinteger

The optional limit parameter limits the number of items that are presented in the response document. Minimum = 1. Maximum = 100. Default = 100.

offsetinteger

The optional offset parameter skips past the specified number of features in the collection. Minimum = 0. Default = 0.

filterstring

The optional filter parameter is a filter expression in CQL format which is applied when retrieving resources to determine which resources are included in a result set.

filter-crsenum

Specify which of the supported CRSs to use to encode geometric values in a filter expression. It must be a 2D coordinate reference system supported by the collection. Default is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).

Options: http://www.opengis.net/def/crs/OGC/1.3/CRS84, http://www.opengis.net/def/crs/EPSG/0/27700, http://www.opengis.net/def/crs/EPSG/0/4326, http://www.opengis.net/def/crs/EPSG/0/3857

filter-langenum

The optional filter-lang parameter is the specific language used for the filter parameter. Default = cql-text

Options: cql-text

Responses

application/geo+json

{ "type": "text", "timeStamp": "2025-02-18T22:39:09.031Z", "links": [ { "href": "text", "rel": "text", "type": "text", "title": "text" } ], "features": [ { "id": "text", "type": "text", "geometry": { "type": "text", "coordinates": [ { "x": 1, "y": 1 } ] }, "properties": { "ANY_ADDITIONAL_PROPERTY": {} } } ] }

{ "id": "text", "type": "text", "geometry": { "type": "text", "coordinates": [ { "x": 1, "y": 1 } ] }, "properties": { "ANY_ADDITIONAL_PROPERTY": {} } }

{ "title": "OS NGD API", "description": "Ordnance Survey National Geographic Database API", "links": [ { "href": "http://data.example.org/", "rel": "self", "type": "application/json", "title": "this document" }, { "href": "http://data.example.org/api?f=json", "rel": "service-desc", "type": "application/vnd.oai.openapi+json;version=3.0", "title": "the API definition" }, { "href": "http://data.example.org/api", "rel": "service-doc", "type": "text/html", "title": "the API documentation" }, { "href": "http://data.example.org/conformance", "rel": "conformance", "type": "application/json", "title": "OGC API conformance classes implemented by this service" }, { "href": "http://data.example.org/collections", "rel": "data", "type": "application/json", "title": "Information about the collections" } ] }

{ "links": [ { "href": "http://data.example.org/collections", "rel": "self", "type": "application/json", "title": "All collections" } ], "collections": [ { "id": "buildingpart", "title": "Building Part", "description": "Polygon feature representing a building.", "links": [ { "href": "http://data.example.org/collections/buildingpart/items", "rel": "items", "type": "application/geo+json", "title": "Building Part" } ], "extent": { "spatial": { "bbox": [ [ -8.82, 49.79, 1.92, 60.94 ] ] }, "temporal": { "interval": [ [ "2022-08-27T00:00:00Z", null ] ] } }, "x-description-html": "<p>Polygon feature representing a building.</p>" } ] }

{ "id": "buildingpart", "title": "Building Part", "description": "Polygon feature representing a building.", "links": [ { "href": "http://data.example.org/collections/buildingpart/items", "rel": "items", "type": "application/geo+json", "title": "Building Part" } ], "extent": { "spatial": { "bbox": [ [ -8.82, 49.79, 1.92, 60.94 ] ] }, "temporal": { "interval": [ [ "2022-08-27T00:00:00Z", null ] ] } } }

{ "description": "text", "layers": [ { "geometryType": "text", "propertiesSchema": { "type": "object", "properties": {} }, "description": "text", "id": "text", "maxTileMatrix": "text", "minTileMatrix": "text", "dataType": "map" } ], "boundingBox": { "crs": "https://example.com", "lowerLeft": [ 1 ], "upperRight": [ 1 ] }, "tileMatrixSetLimits": [ { "tileMatrix": "text", "minTileRow": 1, "maxTileRow": 1, "minTileCol": 1, "maxTileCol": 1 } ], "id": "3857", "title": "text", "tileMatrixSetURI": "https://example.com", "dataType": "map", "crs": "https://example.com", "links": [ { "length": 1, "href": "http://data.example.com/buildingpart/123", "rel": "alternate", "type": "application/geo+json", "templated": true, "varBase": "/ogcapi/vars/", "hreflang": "en", "title": "Building Part" } ] }