Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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 GIS software and web mapping libraries.
These pages should be read in conjunction with the more detailed pages within the Data Structure section and the API's Technical Specification.
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:
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.
The instructions that follow demonstrate how to connect to OS NGD API – Features using Cadcorp SIS Desktop version 9.1.1668.
Cadcorp SIS (version SIS 9 or later).
These instructions are based on Cadcorp SIS Desktop version 9.1.1668.
In Cadcorp SIS Desktop, open an existing map or create a new one.
In the Home tab, click Add Overlay.
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.
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 themes and feature types display in the SWD and map area.
Accessing OS NGD data with OS NGD API – Features via 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 ArcGIS Online.
Access to the ArcGIS Online service.
Sign into your ArcGIS Online account.
Click the Map tab to open the map viewer.
In Layers, click Add > Add layer from URL.
In the Add Layer dialog:
URL: Copy the OS NGD API – Features URL without the API key from your OS Data Hub account and paste it into the text box.
Type: Select OGC feature layer.
Custom parameters:
Select Add custom parameters.
Parameter: Type key in the text box.
Value: Enter your API key.
Click Next.
Select a layer to add: Select a layer to add to the map and then click Add to map.
The layer will display in the Layers panel and the data will display on the map.
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.
QGIS (version 3.12.0 or later).
These instructions are based on QGIS version 3.22.0
Open an existing project or create a new one.
Deselect the Render checkbox in the bottom bar, if necessary.
In Data Source Manager | WFS > Server Connections, click New.
In the Create a New WFS Connection dialog, provide the service details:
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.
You 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.
QGIS saves the connection details and lists the new connection in the Server Connections dropdown for future use.
In Data Source Manager | WFS > Server Connections:
Select your new connection in the dropdown, if necessary.
Click Connect.
When you click Connect, a list of features available in OS NGD API – Features populates in the main box.
In Data Source Manager | WFS:
Features: Select the features you want to load. You can select multiple layers using your Ctrl key.
As a best practice, only load features that relate to your current task – not all features. 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 rate limits.
Only request features overlapping the view extent: Select this option. This engages the bounding box which is set by your viewing window. This means that only selected features within the viewing window will load (not all features).
Click Add to add the features.
Optionally, click Close to close the dialog.
Select the Render checkbox in the bottom bar on the main UI, and select the checkbox next to each feature you want to display in the Layers panel.
Accessing OS NGD API - Features via Leaflet
OS Maps API and OS NGD API - Features added to an API project in the OS Data Hub with an API Key.
A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files
Create a new HTML file with a text editor (e.g. Notepad, Visual Studio Code)
Add the basic HTML structure to your file with a placeholder <div>
for the map.
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 NGD Feature Type and version (e.g. bld-fts-buildingpart-1).
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 center 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.
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 the 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.
Inside the map.on('moveend',...)
event handler fetches and updates the features based on the map's current extent.
Features within the viewport extent will load initially (first 100 features) and continue to load as you pan and zoom across the map.
Accessing OS NGD API - Features via MapLibre GL JS
OS Maps API and OS NGD API - Features added to an API project in the OS Data Hub with an API Key.
A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files
Create a new HTML file with a text editor (e.g. Notepad, Visual Studio Code)
Add the basic HTML structure to your file with a placeholder <div>
for the map.
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 NGD Feature Type and version (e.g. bld-fts-buildingpart-1).
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.
Initialize 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.
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 center point of the map.
zoom
: Sets the initial zoom level of the map.
Create an empty GeoJSON placeholder to hold the feature objects called by the 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 the 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.
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.
Inside the map.on('moveend',...)
event handler fetches and updates the features based on the map's current extent.
Features within the viewport extent will load initially (first 100 features) and continue to load as you pan and zoom across the map.
A preloaded base map, for example, .
OS NGD API – Features added to an API project in the OS Data Hub. See for more information.
A preloaded base map, for example, .
OS NGD API – Features added to an API project in the OS Data Hub. See for more information.
A preloaded base map, for example, .
OS NGD API – Features added to an API project in the OS Data Hub. See for more information.
Click (Add WFS Layer icon) in the Manage Layers toolbar on the left. To activate this toolbar, go to View > Toolbars and select Manage Layers Toolbar.
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.
Congratulations! You've successfully created a map using Leaflet and added an NGD layer using the OS NGD API - Features in a few steps. Continue to explore Ordnance Survey's to learn more about advanced features and functionality such as adding markers, pop-ups, and additional layers.
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 pf features for creating maps with custom styles, markers and interactivity.
Congratulations! You've successfully created a map using MapLibre GL JS and added an OS NGD layer using the OS NGD API - Features in a few steps. Continue to explore Ordnance Survey's to learn more about advanced features and functionality such as adding markers, pop-ups, and additional layers.
Accessing OS NGD data with OS NGD API - Features 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.
OS Maps API and OS NGD API - Features added to an API project in the OS Data Hub with an API Key.
A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files
Create a new HTML file with a text editor (e.g. Notepad, Visual Studio Code)
Add the basic HTML structure to your file with a placeholder <div>
for the map.
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 NGD Feature Type and version (e.g. bld-fts-buildingpart-1).
Create a source for the basemap layer using the OS Maps API and initialize the ol.map
class with the applicable map properties - target
, layers
and view
. Add the following code inside the JavaScript block:
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.
Define and initialize 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 the OS NGD API - Features will be loaded based on the visible map extent.
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.
Features within the viewport extent will load initially (first 100 features) and continue to load as you pan across the map.
Congratulations! You've successfully created a map using OpenLayers and added an OS NGD layer using the OS NGD API - Features in a few steps. 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.