> For the complete documentation index, see [llms.txt](https://docs.os.uk/more-than-maps/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.os.uk/more-than-maps/os-ngd-migration/comparison-of-os-apis/comparison-of-feature-apis.md).

# Comparison of Feature APIs

Comparing the OS Features API and OS NGD API – Features to aid in migration.

## Overview

The purpose of this page is to compare the OS Features API and OS NGD API – Features to help inform your decision about which API is best suited to provide you with access to authoritative Ordnance Survey feature data. Both OS Features API and OS NGD API – Features enable organisations to retrieve and analyse geographic features such as buildings, transport networks and land use. While the core use case for both APIs remains similar, they are built on different data models and technology standards, reflecting the evolution from traditional OS products towards the OS National Geographic Database (OS NGD). 

Understanding these differences can help you identify the potential benefits of the OS NGD API – features and help you to assess the migration effort required to upgrade.

OS Features API provides access to MasterMap generation products. OS NGD API – Features provides access directly to the OS National Geographic Database (NGD), Ordnance Survey's modern geospatial platform.

## Key benefits

The OS NGD API – Features offers several key advantages over the OS Features API. These are compared and summarised below.

### Built for modern development

OS Features API is based on the OGC Web Feature Service (WFS), a mature GIS standard.

OS NGD API – Features uses the newer OGC API – Features standard, providing:

* RESTful APIs
* Native GeoJSON
* Simpler query syntax

This makes it easier to integrate with web applications, cloud services and automated workflows.

### A different way of organising data

OS Features API is organised around individual products such as MasterMap Topography Layer and MasterMap Highways.

OS NGD API – Features uses a thematic structure based on:

* Themes
* Collections
* Feature types

This makes data easier to discover, navigate and combine across domains.

### Richer querying

Both APIs support spatial and attribute filtering.

OS NGD API – Features also supports capabilities such as:

* Temporal filtering
* CQL queries
* Richer, more consistent attribution

This makes it particularly well suited to analytics, automation and decision-support applications.

## Migration requirements

For most organisations, migration will require:

* Replacing WFS requests with REST API calls
* Updating queries and filters
* Moving from product-based datasets to NGD themes and collections

The benefits of migrating to OS NGD API – Features is access to a more modern standard, a richer data model and a platform that aligns with the future direction of OS data services. This provides an advantage to teams looking to move to a more modern architecture and those looking to unlock richer analytics from OS data.

From a developer perspective, moving from OS Features API to OS NGD API – Features is a shift from a traditional WFS operation-based model to a more modern RESTful, resource-based model.

## Implemenation comparision

OS Features API is exposed through an OGC Web Feature Service, using operations such as `GetCapabilities`, `DescribeFeatureType` and `GetFeature`. OS NGD API – Features is built around OGC API – Features, with endpoints for landing page, conformance, collections, schemas, queryables, features and individual feature resources.

***

### Request structure changes

With OS Features API, developers call a single WFS endpoint and define the action through query parameters:

```
GET /features/v1/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=Topography_TopographicArea
```

With OS NGD API – Features, developers request features from a specific OS NGD collection:

```
GET /features/ngd/ofa/v1/collections/bld-fts-buildingpart-1/items
```

So the migration is not simply changing a base URL. Developers need to move from a WFS request pattern to RESTful requests made against collection-specific endpoints.

***

### Feature type names are replaced by OS NGD collection IDs

In OS Features API, data is requested using WFS feature type names such as:

* `Topography_TopographicArea`
* `Highways_RoadLink`
* `Greenspace_GreenspaceArea`

In OS NGD API – Features, data is requested using OS NGD collection IDs such as:

* `bld-fts-buildingpart-1`
* `trn-ntwk-roadlink-1`
* `lnd-fts-land-1`

A key migration task is therefore mapping existing product-based WFS feature types to the appropriate OS NGD collections. A [suite of migration guides](https://docs.os.uk/more-than-maps/os-ngd-migration) are available to help with this. 

***

### Schema and query discovery is more explicit

In OS Features API, developers use `DescribeFeatureType` to retrieve an XML schema for a feature type.

In OS NGD API – Features, schema and query information are exposed through separate REST endpoints:

```
GET /collections/{collectionId}/schema
GET /collections/{collectionId}/queryables
```

This makes it easier for applications to discover available attributes and understand which fields can be queried, particularly when building dynamic search tools, validation logic or automated workflows. 

***

### Filtering changes from XML filters to CQL

OS Features API supports WFS-style filtering, including bounding boxes and OGC XML filters. 

[OS NGD API – Features supports CQL text filters](https://docs.os.uk/os-apis/accessing-os-apis/os-ngd-api-features/technical-specification#use-of-cql-operators), including comparison, logical, array and spatial operators such as `INTERSECTS`. 

For developers, this is a meaningful change. Existing XML filter logic will usually need to be rewritten, but the resulting CQL filters are typically easier to read and maintain.

***

### Output handling is more web-friendly

OS Features API defaults to XML/GML-style responses, although GeoJSON can be requested using `outputFormat=GEOJSON`.

OS NGD API – Features returns feature collections as `application/geo+json`, which aligns more naturally with modern web mapping libraries, JavaScript applications, cloud services and Python data workflows.

This reduces the need for transformation in many modern application architectures.

***

### Paging and CRS parameters change

OS Features API uses WFS-style parameters such as:

* `count`
* `maxFeatures`
* `startIndex`
* `srsName`

OS NGD API – Features uses more REST-style and explicit parameters such as:

* `limit`
* `offset`
* `bbox-crs`
* `crs`
* `filter-crs`

This means developers should review paging logic and coordinate reference system assumptions during migration.

***

### Individual feature access is simpler

In OS Features API, retrieving a specific feature is usually handled through a `GetFeature` request with a suitable filter or identifier-based query.

In OS NGD API – Features, an individual feature can be requested directly using a collection ID and feature ID:

```
GET /collections/{collectionId}/items/{featureId}
```

This is a cleaner pattern for applications that need to store, retrieve or link directly to individual features.<br>

***

### Historical data access

Both APIs support historical data access, but you interact with them in different ways.

With **OS Features API**, historical data is accessed through a dedicated **archive endpoint**. You specify the archive year as part of the URL, then continue to use the normal WFS request pattern, including `service=WFS`, `request=GetFeature`, `version`, `typeNames`, `bbox`, `filter`, `count` and `srsName`. The archive contains annual snapshots of supported products such as OS MasterMap Topography Layer, OS MasterMap Highways Network, OS MasterMap Integrated Transport Network and OS Open UPRN.

For example:

```
GET /features/v1/wfs/archive/2017
?service=WFS
&version=2.0.0
&request=GetFeature
&typeNames=Topography_TopographicArea
&bbox=...
&key={API_KEY}
```

This means you can treat each year as a separate fixed dataset. It works well where an application needs to compare specific annual snapshots, such as 2017 versus 2020, but it does require the year to be built into the endpoint being called.&#x20;

With **OS NGD API – Features**, historical access is handled through the standard collection item endpoint using temporal query parameters. Instead of changing the endpoint to include a year, you request features from an NGD collection and use `datetime` to specify a point in time or time interval. The NGD API supports time-based queries as part of its feature request model.

For example:

```
GET /features/ngd/ofa/v1/collections/{collectionId}/items
?datetime=2024-01-01T00:00:00Z
&key={API_KEY}
```

or for a time interval:

```
GET /features/ngd/ofa/v1/collections/{collectionId}/items
?datetime=2024-01-01T00:00:00Z/2024-12-31T23:59:59Z
&key={API_KEY}
```

The key migration difference is that OS Features API archive access is endpoint-based, while OS NGD API – Features historical access is query-parameter-based. Existing applications that construct archive URLs such as `/archive/{year}` will need to be redesigned to use NGD collection IDs and temporal filters instead.

You should also note that the historical coverage is different. OS Features API provides access to older product archive annual snapshots, while OS NGD API – Features cannot return data from before the launch of the NGD in 2022 but does enable any time/date to be specified, offering highly granular filtering.&#x20;

***

### Authentication is broadly consistent

Both APIs support API key and OAuth 2.0 client credentials authentication. The OS Features API technical specification lists `api-key`, `api-key-header` and `oauth2` as supported authentication methods, and OS NGD API – Features supports the same authentication options.

This means authentication is unlikely to be the most complex part of migration. In many cases, existing credential management approaches can be retained, subject to the user having access to the relevant API.

Example using an API key:

```
GET /features/ngd/ofa/v1/collections/bld-fts-buildingpart-1/items HTTP/1.1
Host: api.os.uk
key: YOUR_API_KEY
Accept: application/geo+json
```

Example using OAuth 2.0:

```
GET /features/ngd/ofa/v1/collections/bld-fts-buildingpart-1/items HTTP/1.1
Host: api.os.uk
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: application/geo+json
```

The main migration effort is therefore typically focused on request patterns, filtering logic and data structures rather than authentication. Existing integrations that use API keys or OAuth 2.0 with OS Features API can generally adopt the same approach when migrating to OS NGD API – Features.

## Looking ahead

OS Features API will continue to be fully supported until its retirement in summer 2030. Existing solutions built around WFS workflows and OS MasterMap generation products can continue to use the API until then, although migration is encouraged to provide a more modern standard, alignment with the wider OS NGD ecosystem and a richer data model.

Most new projects should consider adopting OS NGD API – Features to provide future longevity and improved data access.

More details on the End of Life migration timeline are available on the [product roadmap page of the OS website](https://www.ordnancesurvey.co.uk/products/roadmap).

## Supporting links

The OS API Documentation site has further information that you may find useful. Some particularly relevant sections that may aid you with migration are:

* [OS NGD API – Features](https://docs.os.uk/os-apis/accessing-os-apis/os-ngd-api-features)
  * [What data is available](https://docs.os.uk/os-apis/accessing-os-apis/os-ngd-api-features/what-data-is-available) – This page details the OS NGD datasets available through the OS NGD API – Features.
  * [Getting started](https://docs.os.uk/os-apis/accessing-os-apis/os-ngd-api-features/getting-started) – This page provides an overview of how to get started using OS NGD API – Features.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.os.uk/more-than-maps/os-ngd-migration/comparison-of-os-apis/comparison-of-feature-apis.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.