What is the OS NGD?

How do I access the OS NGD?

Who can use the OS NGD?

What's next?

What's next?

What's the OS NGD?

What's available on this site?

This self-serve site is where you will find documentation to help you get started using OS NGD data via the download service of OS Select+Build and the two OS NGD APIs. Using the left-hand-side navigation menu, you can select and view pages and sections of interest, including:

The key benefits of the OS National Geographic Database (NGD) to customers are as follows:

• Increased data update frequency: With the new OS NGD APIs and OS Select+Build you can access themes of data which are updated up to daily.

• Choose exactly what data you take: For the first time, you can select and build your own data package/s rather than taking pre-selected OS products. For example, if you're only interested in buildings data, then you just select the OS NGD Buildings Theme. There's no need to take a larger product and spend time filtering out the buildings data from it. You can also select data from different OS NGD collections to build your own bespoke data package/s.

• New, easier ways to access data: The download service of OS Select+Build lets you access only the data you need in the format you want. OS NGD API – Features and OS NGD API – Tiles give you online access to the OS NGD to help you quickly request data using the latest OGC API – Features and OGC API – Tiles standards, respectively.

• Customer-friendly data formats: OS NGD data is available in four easy-to-use data formats: GeoPackage, CSV (comma-separated values), GeoJSON (via OS NGD API – Features only) and vector tiles (via OS NGD API – Tiles only).

• More discoverable data: Improved data structures and metadata within the OS NGD, new and bespoke documentation within OS Select+Build, and a brand new online Documentation Platform mean you'll find the right data and support you need quicker than ever before.

• Built with the future in mind: The OS NGD is much more flexible, allowing for changes to the data structure and enhancements to be made when needed to meet evolving customer needs.

• Rich attribution: OS NGD data has been enriched with attribution to ensure that it's straightforward to navigate and query. Attribute names have also been simplified to make them easier to understand.

• Included in the Public Sector Geospatial Agreement (PSGA): Therefore, OS NGD data is free at point of use for Public Sector organisations. It's also available to OS Partners for commercial resell in your solutions.

The OS NGD primarily uses a new identifier called the OSID (OS Identifier) to uniquely identify features. The OSID is used persistently and allows the unique identification of records in the OS NGD. It should be noted that the OSID is not unique across the OS NGD, but rather is only unique at a feature type level. The reason for this is, when possible, the same OSID will be used on multiple features when they represent the same geographical feature. For example, a point feature in the OS NGD Geographical Names Theme which represents a water body will have the same OSID as the more detailed water body representation in the OS NGD Water Features Theme.

Other unique identifiers are also present in the OS NGD. These include the UPRN (Unique Property Reference Number) and USRN (Unique Street Reference Number). These remain the unique identifiers in our data to represent Address and Local Authority Street records, respectively.

The TOID (Topographic Identifier) is also present in the OS NGD, but in most instances this is an optional attribute and therefore should not be relied upon to complete data linking or for implementing COUs. The reason for this identifier being optional is the improved currency on which the OS NGD will be published, meaning the TOID which is created in our existing OS product systems will not always be allocated to features as frequently as they will be accessible via the OS NGD.

OS NGD data is different from our other products because you access it from a single source where you'll find the data you need without having to download whole datasets. It also has a simpler data structure, designed to help you answer questions and develop more intelligent solutions, with quicker loading and implementation.

OS NGD terminology: themes, collections and feature types

Theme

A theme is a macro grouping of features which all represent similar geographic entities. Themes are the highest level of grouping within the OS NGD, and examples include ‘Buildings’ and ‘Transport’.

Themes allow for quick discovery and navigation when using OS Select+Build (the OS NGD download service) or the OS NGD APIs. They also give you the ability to quickly access all OS data relating to your particular theme of interest.

Collection

A collection is a sub-grouping of the OS NGD themes. Collections group together similar types of data within a theme. Examples include ensuring network and routing data is separated from topographic features. For example, in the OS NGD Water Theme, there are two collections: OS NGD Water Features (topographic data) and OS NGD Water Network (network data).

This makes it easier for you to access only the data you require.

Feature type

A feature type is the most granular level of grouping within the OS NGD. Feature types have their own data model and specifications which are not commonly shared with other feature types.

When you order data through OS Select+Build (the OS NGD download service), the data you receive will be provided at a feature type level.

Who can access the OS NGD?

How do you access the OS NGD?

• OS Select+Build: A download service which enables you to choose only the data you require and select how you want to receive your data.

• OS NGD API – Features: An OGC API – Features service.

• OS NGD API – Tiles: A vector tiles service based on OGC API – Tiles.

Sample data for most OS NGD feature types are available through the tool. The sample data always use the latest data schema version available for each feature type.

Downloadable sample data

Sample data for the collections are available in GeoPackage and CSV (comma-separated values) formats.

One zip file of sample data is provided per OS NGD collection. Within each of these zip files, the individual feature types for each collection are separated into their own folder.

Standard sample data areas

The sample data for each OS NGD collection typically cover three 5km x 5km areas in Great Britain: Exeter (England), Newport (Wales), and Inverness (Scotland).

Available formats for OS NGD data

OS NGD data is available in four easy-to-use formats: GeoPackage, CSV (comma-separated values), GeoJSON and vector tiles. The download service of OS Select+Build supports GeoPackage and CSV. OS NGD API – Features supports GeoJSON. OS NGD API – Tiles supports vector tiles.

CSV overview

CSV files are delimited text files which use commas to separate each attribute from the next. CSV is one of the file formats available via OS Select+Build. A single record is commonly provided per line, with a new line being started for each new record.

Geometry attribution will be provided as Well-Known Text (WKT).

CSV offers the following benefits:

• The single file is familiar to many customers and well used across GIS and data science tools.

• It is plug and play with most databases.

• The ability to quickly load large datasets using COPY method rather than INSERT.

CSV structure

The following table shows how different attribute types in the OS NGD are delivered when you choose to receive a CSV format. This includes whether to expect quotes, and how NULL values are treated.

GeoPackage overview

GeoPackage (GPKG) is an open standard data format as defined by the Open Geospatial Consortium (OGC). It is one of the file formats available via OS Select+Build. GeoPackage is designed to be a lightweight format that can contain large amounts of varied and complex data in a single, easy to distribute and ready to use file. Please be advised that older versions of GIS software may need updating before being able to display and interact with GeoPackage files.

GeoPackage offers the following benefits:

• The single file is easy to transfer and offers the end-user a rich experience.

• Attribute names are not limited in length, making it user-friendly.

• The file size limit is very large at 140TB, so lots of data can be easily accommodated (please note that a file size limit may be imposed by the file system to which the file is written).

• It supports raster, vector and database formats, making it a highly versatile solution.

• It is an OGC standard.

• In most cases, it is a plug and play format.

GeoJSON overview

GeoJSON is an IETF standard designed to represent simple geographical features and their non-spatial attributes. It is used for encoding geographic data structures using JavaScript Object Notation (JSON). GeoJSON is used by OS NGD API – Features.

Supported geometry types:

• Point

• LineString

• Polygon

• Multipart geometries: MultiPoints, MultiLineString, or MultiPolygon features

Vector tiles overview

Vector tiles are clipped tiles, or grid squares, composed of layers of vector features which are optimised for caching, scaling and producing map imagery quickly. They serve in a similar way to raster tiles but have the added functionality of being customisable by users. A client application requests tiles based on a zoom level and extent, and the server responds with binary data representing the vector tiles containing the layers to be visualised on that map.

OS NGD API – Tiles serves vector tiles as raw information which is presented using compressed packets of geographic data using the Protocolbuffer Binary Format (.pbf).

Vector tiles offer the following benefits:

• User customisation and styling functionality – customise your map with full and dynamic design control.

• Small file size – lightweight tiles that are efficient and quick to render in your client application.

• Pixel perfect maps – high-resolution, beautiful mapping for all devices (web and mobile devices).

• Snapping ability – due to the data being vector, data can be snapped to and traced.

• Smooth zooming and scaling effect – a seamless user experience when zooming in and out of maps.

• Advanced features – vector tiles contain geographic data (not just images) which can be interrogated and analysed.

File naming

When you place an order for OS NGD data via OS Select+Build, the following file naming convention will be applied to the data you receive:

themeshortcode_collectionshortcode_featuretype

In order to keep file names manageable and not overly long, shortened file names ('short codes') have been used for both the theme and collection. Using short codes in our naming convention also ensures we have consistency in naming between OS Select+Build and the OS NGD APIs.

An example of how these short codes are used is below, with the example showing a file name which would be created for an order of the Built Address Feature Type within the OS NGD GB Address Collection of the OS NGD Address Theme:

add_gb_builtaddress

A full list of the short codes we use in OS Select+Build and the OS NGD APIs is detailed in the following table:

Geographic filtering

There are three options within OS Select+Build (the OS NGD download service) in relation to the geographic extent of your order. These are:

• Great Britain: Receive all data for the whole of Great Britain.

• Customer Specified Area: Draw an area of interest (AOI) and only receive the data which intersects this area.

• Pre-defined Area: Select a pre-defined area, and only receive the data which intersects this area.

Order update options

When accessing the OS NGD, the following order update options will be available:

• One Off Full Supply

• Regular Full Supply

• Change-Only Update (COU; after an initial Full Supply)

• No Update

The following frequencies will be available dependent on the type of order you place:

• Daily Supply: This will provide you with the latest updates OS have loaded and verified for publication since the previous day as a COU file.

• Monthly Supply: Either a Full Supply or COU Supply of all the changes which have occurred in the previous month.

• Annual Supply: A Full Supply of the data to show how the data looked at the end of each year.

Further details about the options available to you can be found further down on this page.

Update files

If you choose to receive a COU supply for your CSV data, this can be provided on either a daily or monthly frequency. In both cases, your COU file will contain any changes which have been made to the underlying data within the selected time frequency. If no changes have been made to a selected feature type of your choice, then you will receive a blank COU file.

File supply

If you use OS Select+Build to access the OS NGD, then a separate download file will be provided for each feature type you order. For example, if your selected theme has two feature types you will be supplied with two separate files (CSV or GeoPackage) as part of your order.

Ordering combinations

The following tables summarise the different options available to you dependent on what you specify when ordering your data through OS Select+Build.

For the purposes of the tables below, the following definitions are being used:

• Unfiltered means a Great Britain supply with no further attribute filters applied.

• Filtered means an order for data which either has a geographic filter applied or an attribute filter applied.

GPKG files

CSV files

Currency of OS NGD data

OS Select+Build and OS NGD API – Features

Whether accessing OS NGD data through OS Select+Build or OS NGD API – Features, the following currency of the data will apply:

For collections that are not updated daily, the table below provides the date of the last update. It also shows the version of the OS MasterMap product to which the OS NGD data corresponds:

OS NGD API – Tiles

Through the OS NGD, Ordnance Survey aims to iterate and release data enhancements quicker than ever before. We want to be able to do this without disrupting customers who have adopted data schemas and are heavily reliant on a specification remaining the same for a longer period of time. With this in mind, the OS NGD is able to run multiple data schema versions for a single feature type at any given time.

When we release a new data schema version in the OS NGD, the changes will be visible on the feature type pages of this documentation platform. As you can see from the image below, each attribute on a feature type page states which data schema version it is present within, with the Version Date attribute in the example below being present in both data schema versions 1.0 and 2.0:

How has data schema versioning been implemented?

As new enhancements are made to a given feature type in the OS NGD which require the schema to be uplifted (for example, new attributes being added, resulting in a major schema version increment from 1.0 to 2.0), the new data schema version will become available via the OS NGD access services (i.e. OS Select+Build and the OS NGD APIs).

There are two types of version increments that can be applied:

• Minor: A non-breaking change that does not usually impact a customer’s implementation of the data, for example, the addition of an attribute value to a code list.

• Major: A significant breaking change that usually impacts a customer’s implementation of the data, for example, the addition or removal of an attribute.

When a data schema undergoes a minor version increment, the previous version will no longer be available. This is because the change is deemed to be so small that there is little to no work involved in customers migrating to the latest version of the data.

When a data schema undergoes a major version increment, the previous version will become known as being in 'maintenance' and the new data schema version will be known as the ‘latest’. This reflects an understanding of the work required for customers to move to a new version and allows time for this to happen.

When using the OS NGD access services, you will be able to choose which data schema version you want to use for feature types when ordering or interacting with the data where more than one major version exists. You can choose from data schema versions which are in the 'latest' or 'maintenance' states.

Older data schema versions (i.e. those in a maintenance state) will remain in the OS NGD for a period of time; it's important to note that these maintenance versions will continue to receive updates. Before any data schema version is retired for a given feature type (i.e. when it no longer receives updates and will be removed from the ordering and selection process), customer communications will be distributed, and a notice period will be issued to allow sufficient time for customers to upgrade to a newer version of a data schema.

Code list versioning

Code lists within the OS NGD have only one type of version increment applied: major.

When a code list undergoes a major version increment, all feature types that implement the code list will undergo a minor version increment, reflecting the data change that will occur.

Worked example

In the worked example below, we demonstrate how a feature type has new major data schema versions released (v2.0 and then v3.0), while maintaining older data schema versions (v1.0 and then v2.0), before the original data schema version (v1.0) moves into end of life and is retired.

• In this example, the feature type starts with a single data schema version (v1.0), known as the latest data schema version.

• At a point in the future, data enhancements are made which require the data schema version to be uplifted, so a second major data schema version (v2.0) is released. As there can only be one latest data schema version (v2.0), the original data schema version (v1.0) drops down into maintenance – but it still receives updates and is still accessible to customers via the OS NGD access services.

• Further again into the future, additional new enhancements are made to the feature type, requiring a third major data schema version (v3.0) to be released. Again, as before, there can only be one latest data schema version for a feature type (v3.0), so the second data schema version (v2.0) drops down into maintenance. Two major data schema versions (v1.0 and v2.0) are now in maintenance, but again, both are still receiving updates and are accessible to customers via the OS NGD access services.

• At a future point, and after customer communications have been distributed and a formal notification period has elapsed, it is decided to retire the original data schema version (v1.0). V1.0 moves into the end of life state, where it stops receiving updates and can no longer be accessed by customers via the OS NGD access services. V3.0 remains the latest data schema version and v2.0 remains in maintenance, with both data schema versions receiving updates and being accessible to customers via the OS NGD access services.

Annual Full Supply orders and data schema versioning

If you select an Annual Full Supply frequency for your OS NGD data order in OS Select+Build, we will provide you with the data as it was on 01 January of the current year. This means if a new feature type or a new data schema version of an existing feature type was released after 01 January and you order either of these as part of your Annual Full Supply, you will receive an empty data package for the newly released feature type / new data schema version of an existing feature type. The data for the new feature type / new data schema version of an existing feature type will then be included in your supply on the next 01 January after the release.

For example, the March 2025 OS NGD data enhancements release contained 3 new feature types (Building Access Location, Crowd Sourced Name Point, and Street Light), and 11 new data schema versions (Building v4.0, Building Part v2.1, Land v3.1, Path Link v2.0, Rail v3.1, Road Link v4.0, Road Track Or Path v3.1, Site v2.2, Site Access Location v2.0, Structure v3.1, and Water v3.1). The data for the new feature types and the new data schema versions will not be part of Annual Full Supply orders until 01 January 2026.

OS Select+Build

The GeoPackage and CSV formats accessible via OS Select+Build are available in four different coordinate reference systems dependent on your selection:

• British National Grid (BNG: EPSG: 27700)

• British National Grid + ODN Height (EPSG: 7405)

• European Terrestrial Reference System (ETRS89: EPSG: 4258)

• World Geodetic System (WGS84: EPSG: 4326)

Default coordinate reference systems for OS Select+Build

The following table outlines the default coordinate reference system used by each OS NGD collection in OS Select+Build:

Selecting a coordinate reference system

If you don't choose a particular coordinate reference system for your data package, OS Select+Build will automatically select the default coordinate reference systems for the feature types in your data package for you.

OS NGD APIs

OS NGD API – Features

The GeoJSON format accessible via OS NGD API – Features is available in four different coordinate reference systems:

• British National Grid (BNG: EPSG: 27700).

• World Geodetic System (WGS84: EPSG: 4326)

• British National Grid + ODN Height (EPSG: 7405)

• Web Mercator (EPSG: 3857)

OS NGD API – Tiles

The vector tiles format accessible via OS NGD API – Tiles is available in two different coordinate reference systems:

• British National Grid (BNG: EPSG: 27700)

• Web Mercator (EPSG: 3857)

Definitions for the coordinate reference systems available in the OS NGD

• Name and Definition: The name of the attribute and what it is describing.

• Data Types: The values the attribute can take. For example, a numeric value or a string. This is provided for all three data formats – GeoJSON, GeoPackage, and CSV.

• Nullable: A True or False value to denote whether the attribute always has to be populated with a value (False) or can be NULL (True).

• Code List Name: The name of the code list used in association with the attribute (if applicable) and a hyperlink to the page displaying that code list.

• Max Length: Values are given here to indicate the maximum length that you will find in the attribute, to aid in developing applications.

• Multiplicity: Describes how many times this value is expected to be populated in the data. These values may be used in combination.

  • 1: There must be a value.

  • 2: There must be two values.

  • n: There may be one or more values.

  • 0: Population is optional.

• OS NGD API – Features Filterable: A Yes / No value to denote whether you can refine your query in OS NGD API – Features specifically on this attribute.

• OS Select+Build Filterable: A Yes / No value to denote whether you can refine your order in OS Select+Build on this attribute.

Change-Only Updates (COUs) are only available for CSV data supplies of the OS NGD. The benefit of taking COU supplies is that you only receive the features which have changed since your last supply, reducing the overall size of the files you receive.

Upon OS NGD launch, if you choose to receive a COU supply for your CSV data, this can be provided on either a daily or monthly frequency. In both cases, your COU file will contain any changes which have been made to the underlying data within the selected time frequency. If no changes have been made to a selected feature type of your choice, then you will receive a blank COU file.

The key attribution required to use and implement a COU is detailed below:

• Unique Identifier: The unique identifier for the feature type you are using is how you will ensure you are updating the correct records in your data holdings. In most instances the unique identifier will be the OSID, but this is not always true, therefore please check the appropriate feature type pages in our documentation.

• Version Date: This is the date when the feature was last updated in OS product databases.

• Version Available From Date: This is the date when the feature became the latest version and was published to customers.

• Version Available To Date: This is the date when the feature was superseded by an update or ceased to exist.

• Change Type: This is a code list which gives more information about the type of change which has occurred.

What is GeoPackage?

Key features and benefits of GeoPackage

GeoPackage offers users the following key features and benefits:

• The single file is easy to transfer and offers the end-user a rich experience.

• Attribute names are not limited in length, making the format user-friendly.

• The file size limit is very large at 140 TB, so lots of data can be easily accommodated (please note that a file size limit may be imposed by the file system to which the file is written).

• It supports raster, vector and database formats, making it a highly versatile solution.

• It is an OGC standard.

• In most cases, it is a plug and play format.

• Data will be supplied in British National Grid (ESPG:27700), World Geodetic System (WGS84: EPSG: 4326), or British National Grid + ODN Height (EPSG: 7405), depending on your selection when ordering OS NGD data.

Accessing GeoPackage data via GIS software

The following sub-sections provide step-by-step instructions on how to access GeoPackage data via various GIS software packages, all current versions of these support GeoPackages natively.

Converting / Loading a GeoPackage to other data formats

It is possible to use Extract, Transform, Load (ETL) tools to convert the data into different formats and to load into databases.

Introduction

The following pages provide an overview of the OS National Geographic Database (OS NGD); they cover the core elements of its design, including data formats, the coordinate reference systems used, and how Change-Only Updates (COUs) will be provided, amongst other topics:

FME is a data integration platform which can read the GeoPackage format and be used to convert and transform the data into other formats or databases. The below example shows how to read a GeoPackage into an FME workbench.

Requirements

• FME Desktop

• An FME license

• A GeoPackage dataset

Instructions

Requirements

• CadCorp SIS (version SIS 9 or later)

• A GeoPackage dataset

Instructions

These instructions were created using CadCorp SIS 9 Desktop Express; however all versions of CadCorp SIS 9 or later support GeoPackage.

Requirements

• QGIS (version 2.10.1 or later)

• A GeoPackage dataset

Instructions

These instructions were created using QGIS version 3.22. Other versions of QGIS can be used, from version 2.10.1 onwards.

Requirements

• ArcGIS Pro (version 1.1 or later)

• A GeoPackage dataset

Instructions

These instructions were created using ArcGIS Pro version 2.5, but versions from 1.1 onwards will support GeoPackage.

What is a CSV file?

A comma-separated values (CSV) file is a common interchange format for spreadsheets and databases which facilitates a simplistic use of data. Each field is either textual or numeric. Within the CSV, each field is separated from the next by a comma. CSV file format is universally supported for easy ingestion into all major database products.

Please be aware that CSV files are designed to be opened in a database or GI system, and opening them in other software applications could corrupt the data. In particular, Excel has a row limit which might be exceeded by some of our CSV files containing OS NGD data, depending on the order you placed and its size. We recommend that you load CSV files containing OS NGD data directly into a database or GI system, rather than trying to open these files in Excel.

Key features of OS NGD CSV format

CSV offers users the following key features:

• Change-Only Update (COU) files are only supplied in CSV format (they are not supplied in GeoPackage format)

• Geometry provided as Well-Known Text (WKT)

• Header rows included in the file

• There will be one record per line in each file

• Fields will be separated by commas

• Where string fields contain commas, they will be delimited by double quotes

• Double quotes inside strings will be escaped by doubling

• Records will be terminated by Carriage Returns and Line Feeds

• CSV files will be Unicode encoded in UTF-8

Requirements

• ArcMap (version 10.2.2 or later)

• A GeoPackage dataset

Instructions

These instructions were created using ArcMap version 10.7, but versions from 10.2.2 onwards will also support GeoPackage features.

Introducing attribute filtering

The following sub-sections give step-by-step instructions on how to add attribute filters to a new recipe and provide worked examples of creating both simple and nested filters.

How do I add attribute filters to a new recipe?

To add attribute filters to a new recipe:

Worked example of creating a simple filter

In the following worked example of creating a simple filter, we will use the OS NGD Buildings Theme and select the Building Part Feature Type from the Building Features Collection. Our aim is to build a filter to select buildings where education is recorded as the land use.

Worked example of creating a nested filter

What if, in addition to the simple filter above (returning results for buildings with a land use of education), we want those results to show only buildings over 15 metres in height? What if you also wanted to add an additional filter to show buildings with a land use of rail? To achieve this, you could create a nested filter using the + Add group option.

How do I check if filters are used in an existing recipe?

To check what filters have been applied to feature types in an existing recipe:

Requirements

• GDAL version 1.11.0 or above (with access to a command line interface to use it)

• A GeoPackage dataset

Instructions

ogrinfo wtr_ntwk_waterlinkset.gpkg

INFO: Open of `C:\wtr_ntwk_waterlinkset.gpkg'
      using driver `GPKG' successful.
1: wtr_ntwk_waterlinkset
2: wtr_ntwk_waterlinkset_wtrlinkref (None)

ogrinfo wtr_ntwk_waterlinkset.gpkg -so -al

INFO: Open of `C:\wtr_ntwk_waterlinkset.gpkg'
      using driver `GPKG' successful.
Layer name: wtr_ntwk_waterlinkset
Geometry: Unknown (any)
Feature Count: 116
Extent: (209562.134000, 79229.510000) - (341688.834000, 853194.875000)
Layer SRS WKT:
PROJCRS["OSGB 1936 / British National Grid",
[...]

ogr2ogr -f PostgreSQL "PG:user=example_user password=example_password dbname=postgres host=localhost port=5432 active_schema=example_schema" wtr_ntwk_waterlinkset.gpkg

schemaname     | tablename
---------------+---------------------------------
example_schema | wtr_ntwk_waterlinkset
example_schema | wtr_ntwk_waterlinkset_wtrlinkref

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.

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.

Introducing temporal filtering

Temporal filtering allows you to order a one-off snapshot of data from the OS National Geographic Database (NGD) from a current or past date.

How do I add a temporal filter to a new data package?

To create a new OS NGD data package and apply a temporal filter to it:

It is recommended that you have a basic understanding of database terminology before following the guides in the tabs below. The guides contain generic instructions, and it is recognised that there are multiple ways to load CSV files into databases which may be more suitable to your environment and existing processes.

What is OS Select+Build?

For the first time, you can select and build only the data you require rather than taking off-the shelf OS products. For example, if you're only interested in buildings information, then you just select the OS NGD Buildings Theme and the content you require within that theme. There's no need to take a whole product and spend time filtering out the data you need from it.

You can also take data from different OS NGD collections. For example, you could select the Building Line and Building Part Feature Types (which are both in the Building Features Collection of the Buildings Theme) and the Structure Line Feature Type (which is in the Structure Features Collection of the Structures Theme).

The screenshot below shows what selecting this data would look like using OS Select+Build. The secondary navigation menu on the left-hand side of the screen is where you select the feature types you want from the tree view of the OS NGD themes, collections, and feature types, and where you can apply filters to the feature types (if needed). The right-hand side panel displays the definition for the feature type you've selected and lists all the attributes present within it.

Recipes

What is a recipe?

A recipe is a bespoke selection of OS NGD data which is made by a user within OS Select+Build. Recipes allow you to choose the OS NGD data that best fits your requirements.

Every new recipe you create will be stored in your OS NGD Select+Build Recipe Library. This library will be visible to other people in your organisation. It provides a central place for colleagues to view and use recipes.

How do I create a new recipe?

Before you create a data package to receive your OS NGD data, you'll need to create a recipe.

To create a new recipe:

• Select Download from the main menu.

• Choose OS Select+Build from the secondary navigation menu.

• Click the Create a new recipe button.

• Add the following details to your recipe under Create your recipe in the secondary navigation menu:

  • Give your recipe a name.

  • Add a description for your recipe.

  • Select your OS NGD data by choosing the themes, collections and feature types you want to include in your recipe.

  • If you wish to choose which schema version (where applicable) you'd like to receive the data in for a feature type, click on the feature type name within the tree view in the secondary navigation menu, then choose a data schema version from the drop-down box in the right-hand side panel.

  • Add filters to the feature types, if needed.

• Click the Create recipe button.

Your new recipe will now instantly be available in your OS Select+Build Recipe Library.

How do I find my OS Select+Build Recipe Library?

Any recipes created by your organisation will be stored in your OS Select+Build Recipe Library in the OS Data Hub.

To find your OS Select+Build Recipe Library:

• Select Download from the main menu.

• Choose OS Select+Build from the secondary navigation menu.

You will then be taken to your organisation's OS Select+Build Recipe Library.

How do I check what's in a recipe?

You can easily check details about any of your organisation's existing recipes, including a recipe's name, description, creation date, author, the filters used (if applicable), and what OS NGD themes, collections and feature types are included in a recipe.

To check what's in an existing recipe:

• Select Download from the main menu.

• Choose OS Select+Build from the secondary navigation menu.

• In your OS NGD Select+Build Recipe Library, scroll or search for the recipe you would like to find out more about.

• In this view, you can see the following high-level details about a recipe:

  • The recipe's name

  • The recipe's author

  • The date the recipe was created

  • A description of the recipe, if one has been added

  • OS NGD theme tags to show which themes are included in the recipe

In the screenshot below, you can see that the example recipe includes the following OS NGD themes: Land, Buildings, and Structures.

To see what OS NGD themes, collections and feature types are in a recipe, follow the steps above to find a recipe in your OS Select+Build Recipe Library, then:

• Click on the name of the recipe you would like to find out more about.

• You are now within the Recipe details screen, where you can view detailed information about the recipe, including:

  • The recipe's name

  • A description of the recipe, if one has been added

  • An option to view all of the filters applied to feature types in the recipe (if applicable)

  • The date the recipe was created

  • The recipe's author

  • An option to show the data schema version of each feature type in the recipe

  • A recipe tree detailing the OS NGD themes, collections, and feature types included in the recipe

How do I delete a recipe?

A recipe can be deleted within your recipe library. You can do this if you are the author of the recipe or an admin user.

To delete a recipe:

• Select Download from the main menu.

• Choose OS Select+Build from the secondary navigation menu.

• In your organisation's OS Select+Build Recipe Library, scroll or search for the recipe you want to delete.

• Click on the name of the recipe to view the recipe details.

In this view, you will be able to see the Recipe actions dropdown

• Click the Recipe actions dropdown.

• Click the Delete recipe button.

• Click on the name of the recipe to view the recipe details.

  • If there are no data packages associated with the recipe, you will be asked to confirm the deletion of the recipe.

  • Where there are data packages associated, you will see the following warning:
• Click the Delete recipe button.

How do I edit the name of my recipe?

To edit a recipe's name:

• Select Download from the main menu.

• Choose OS Select+Build from the secondary navigation menu.

• In your organisation's OS Select+Build Recipe Library, scroll or search for the recipe you want to edit.

• Click on the name of the recipe to view the recipe details.

• Click on the pencil icon next to the recipe name.

• Enter the required changes to the recipe name.

• To save your changes, simply click away from the edit box.

How do I edit the description of my recipe?

To edit a recipe's desciption:

• Select Download from the main menu.

• Choose OS Select+Build from the secondary navigation menu.

• In your organisation's OS Select+Build Recipe Library, scroll or search for the recipe you want to edit.

• Click on the name of the recipe to view the recipe details.

• Click on the pencil icon next to the recipe description.

• Enter the required changes to the recipe description.

• To save your changes, simply click away from the edit box.

How do I share a recipe?

A recipe can be shared with another organisation to enable collaboration.

To share a recipe:

• Select Download from the main menu.

• Choose OS Select+Build from the secondary navigation menu.

• In your organisation's OS Select+Build Recipe Library, scroll or search for the recipe you want to share.

In this view, you will be able to see the Share recipe button; please note that you can only share recipes created by your organisation.

• Click the Share recipe button.

The share recipe dialog will appear.

• Search for the organisation with whom you wish to share the recipe. To do this, just start to type the organisation's name, then select the correct organisation from the list.

• Add a message for the organisation receiving the recipe to provide them with context around why you are sharing the recipe with them.

• Click Send.

How do I accept a recipe shared with me?

To accept a shared recipe:

You will see a new notification at the top right of your screen, indicated by a bell button and a number count of any unread notifications.

• Click the bell button.

You will then see details of a notification explaining You have been sent a shared recipe, which will include the name of the organisation that shared the recipe with you, along with a message if they added one when sharing the recipe.

• Click View recipe details.

The recipe details will be displayed for you to review. If you are happy with the shared recipe:

• Click the Accept recipe button.

You will be presented with a dialog box explaining: When you accept a recipe, it is added to your organisation’s recipe library. It will show as 'shared'. You can create data packages from it, but you can’t share the recipe with other organisations.

How do I reject a recipe shared with me?

To reject a shared recipe:

You will see a new notification at the top right of your screen, indicated by a bell button and a number count of any unread notifications.

• Click the bell button.

You will then see details of a notification explaining You have been sent a shared recipe, which will include the name of the organisation that shared the recipe with you, along with a message if they added one when sharing the recipe.

• Click View recipe details.

The recipe details will be displayed for you to review. If this recipe is not right for you and you want to reject it:

• Click the Reject button.

Data packages

How do I create a new data package?

Once you've created a recipe, you'll then need to create a data package against it to receive your OS NGD data.

To create a new OS NGD data package:

• Select Download from the main menu.

• Choose OS Select+Build from the secondary navigation menu.

• In your OS NGD Select+Build Recipe Library, scroll or search for the recipe you wish to create a data package against, select that recipe, then click the Add data package button.

• Add the following details to your data package under Add a data package in the secondary navigation menu:

  • Give your data package a name.

  • Choose the area you want to receive your data for: Either all of Britain or Predefined Area (this means you receive data and it will not be refined by location) or Draw a polygon / upload a file / use an OS polygon to select a smaller area for your data to be provided for.

  • Select the updates you want: Either not required or COU (Change-Only Update) frequency. There is also an option to select a one-off snapshot of a current or past date.

  • Set your initial supply date.

• Click the Create data package button.

You will receive an email confirming that your data package is being created and another one when your new data package is ready to download.

How do I find and download an existing data package?

All OS NGD, OS OpenData and OS Premium data packages created and ordered by your organisation will be catalogued in your Data packages list in the OS Data Hub.

To find and download an existing data package:

• Select Download from the main menu.

• Choose Data packages from the secondary navigation menu.

You will be then taken to your Data packages list.

• Scroll through the list to find a particular data package or use the search bar to search by data package name, data package number, or product name.

Data packages linked to an OS NGD recipe can be identified by their prefix of 'OS NGD Recipe' against the recipe name in the Product column in the Data packages list:

• Once you have found the data package you want from the list, click the Download button in the Status column.

You are now within the Data package summary screen, where you can view and download files. Under 'Individual file downloads' in the bottom left-hand side of your screen, you will see a .zip file for every feature type in your data package order.

• Click on a file to download it.

What is the Order Summary file?

This is also known as a manifest file, a computing file which contains metadata. We provide an Order Summary file for each feature type in your data package. The following file naming convention will be applied to each Order Summary file you receive:

• collection_featuretype_orderSummary.jso

For example, the file name for the Building Part Feature Type Order Summary file would look like this:

• bld_fts_buildingpart_orderSummary.jso

The example below shows the information an Order Summary file contains:

{
 "featureName": "bld-fts-buildingline",
 "crs": "http://www.opengis.net/def/crs/EPSG/0/27700",
 "schemaVersion": "1.0",
 "validFromDate": null,
 "validToDate": "2023-03-01",
 "recordCount": 202653
}

Things to remember

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. The service offers the following endpoints:

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:

What is OS NGD API – Features?

Things to remember for OS NGD API – Features

The process to load the COU files will depend on a number of factors based on your own environment and requirements, including:

• Database software

• Data loading method or software

• Feature retention and lifecycle requirements

Feature retention options

There are two main scenarios that represent either extreme of the feature lifecycle options:

1. Latest feature view

2. Full feature archive

Latest feature view

In this scenario, the COU files are processed and only the current version of every feature is retained. This will result in the same data holdings that would be achieved if a new full supply was received on this date.

To achieve this, either post-processing will have to be done once all COU data is loaded into a database, or the loading process will need to evaluate the COU data against your existing data and process accordingly. This processing will be based on the supplied attributes which detail the type of change and the dates for that version.

Change type

Each feature type is supplied with a Change Type attribute (changetype), which is populated from a code list value (changetypevalue).

Below is a table of the possible change types and the resultant actions required to maintain a latest feature view of the data for the specific feature type. Individual features should be targeted based on that feature type's unique identifier. In the majority of feature types, this will be the osid, but this is not always the case; therefore, please check the appropriate feature type documentation.

Version dates

A single feature may be updated multiple times in a single COU file when multiple changes occur within the selected COU frequency. Instead of suppressing all changes other than the last edit, the COU will contain all of the edits which have been made to that feature.

To obtain the current 'live' view of a feature, the latest edit is required; all previous edits can be discounted. In essence, this requires the following two processes:

1. Discarding all feature records with the exception of the latest Version Available From Date (versionavailablefromdate)

2. Discarding all feature records that have a Version Available To Date (versionavailabletodate) populated, i.e. it is NOT NULL. These records will also have the Change Type Value (changetypevalue) of 'End Of Life' or 'Moved To A Different Feature Type'.

Full feature archive

In this scenario, every record is retained, giving a full lifecycle since the supply started of each feature. This will result in multiple records for each feature.

To enable this in a database, the default primary keys (as defined in the provided DDL scripts) will have to be changed to also include the version available from and to dates (versionavailablefromdate, versionavailabletodate).

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

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.

Instructions

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:

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

Instructions

What you'll need

• A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files.

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.

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

What you'll need

• A text editor like Visual Studio Code or Notepad to edit and save your HTML and JavaScript files.