> 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-vector-tile-apis.md).

# Comparison of Vector Tile APIs

Comparing the OS Vector Tile API and OS NGD API – Tiles to aid in migration.

## Overview

The purpose of this page is to compare the OS Vector Tile API and OS NGD API – Tiles to help you decision which API is best suited to provide a customisable basemap for your project. Both APIs provide a flexible, high-performance basemap that can be used with most modern web mapping libraries. The OS Vector Tile API is built on traditional OS products and provides a cartographic view of that data through vector tiles. In comparison, OS NGD API – Tiles is powered by the OS National Geographic Database (OS NGD) and based on the latest [OGC API – Tiles standard](https://docs.ogc.org/is/20-057/20-057.html).

## Key benefits

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

### Built for modern architectures

While both services provide vector tiles, OS NGD API – Tiles is built on the OGC API – Tiles standard, making it more interoperable and better aligned with modern geospatial and cloud-native architectures.

This enables organisations to maintain open standards, improve interoperability and reduce dependency on platform specific implementations to provide greater project longevity.

### Optimised for performance

OS NGD API – Tiles delivers a curated subset of OS NGD data specifically optimised for visualisation. This means that the tiles provided are lightweight and responsive while still maintaining access to feature rich OS NGD data.

The result is a basemap that:

* Loads quickly
* Scales efficiently
* Maintains clarity across zoom levels

For most users, the mapping experience will feel familiar, while benefiting from a more streamlined data model.

### Styling and flexibility

If you're already using the OS Vector Tile API, the styling approach of OS NGD API – Tiles will feel familiar. 

OS NGD API – Tiles supports:

* Custom styles
* British National Grid and Web Mercator projections
* Common web mapping libraries including MapLibre, OpenLayers and Leaflet

Because the service uses an OS NGD aligned data model, some layer names and structures differ from the OS Vector Tile API. When migrating to OS NGD API – Tiles, existing styles may need to be updated.

In return, you gain access to a more flexible basemap architecture and the ability to combine core mapping with additional OS NGD derived thematic layers.

## Migration requirements

For many organisations, migration between the two services is straightforward.

A basic migration typically involves:

* Updating the API endpoint
* Switching to an OS NGD API – Tiles style
* Reviewing layer mappings and custom styling

For applications with heavily customised cartography, some additional testing and style changes may be required.

Migration can also be an opportunity add additional features and functionality. By combining OS NGD API – Tiles with OS NGD API – Features, organisations can create applications that not only display data but also query, analyse and interact with it through a consistent OS NGD data model.

Implementation comparison

Although both the OS Vector Tile API and the OS NGD API – Tiles deliver vector tiles, developers interact with them in different ways. The OS Vector Tile API follows a simpler, service specific tile pattern, while OS NGD API – Tiles exposes a more structured OGC API – Tiles interface with discoverable collections, tile matrix sets, styles and tile resources. 

### Endpoint structure is different

The OS Vector Tile API has three main endpoint types: service metadata, stylesheet and tile request. OS NGD API – Tiles exposes landing page, conformance, collections, collection, tile matrix sets, tiles and styles endpoints.

With the OS Vector Tile API, a typical tile request is based around a fixed tile path:

```
GET https://api.os.uk/maps/vector/v1/vts/tile/{z}/{y}/{x}.pbf?key={API_KEY}&srs=3857
```

For overlays, the layer name is inserted into the URL:

```
GET https://api.os.uk/maps/vector/v1/vts/{layer-name}/tile/{z}/{y}/{x}.pbf?key={API_KEY}&srs=3857
```

For example, `{layer-name}` can be values such as `boundaries`, `greenspace`, `sites`, `water`, `highways` or `paths`.

With OS NGD API – Tiles, the request is organised around an OGC-style collection:

```
GET https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles/{tileMatrix}/{tileRow}/{tileCol}?key={API_KEY}
```

For example, `{collectionId}` may be `ngd-base`, `asu-bdy`, `wtr-ctch`, `trn-ntwk-railway` or `wtr-tidalboundary`.

In practical terms, this means a developer is not just switching from one tile URL to another. They are moving from a product-specific tile endpoint to a collection-based API structure where the collection forms part of the request model.

***

### The meaning of the tile coordinates is slightly reframed

In the OS Vector Tile API, tile requests use the familiar `{z}/{y}/{x}.pbf` pattern, where `z` is the zoom level and `x` and `y` are the tile coordinates. The spatial reference system is passed as a query parameter using `srs`, with supported values of `27700` and `3857`. 

In OS NGD API – Tiles, the equivalent request uses `{tileMatrix}/{tileRow}/{tileCol}`. This is aligned to OGC API – Tiles terminology, where the `tileMatrix` identifies one of the scales defined in the tile matrix set, and `tileRow` and `tileCol` identify the tile location within that matrix.

So, conceptually:

```
OS Vector Tile API:
z / y / x

OS NGD API – Tiles:
tileMatrix / tileRow / tileCol
```

For many web map libraries, this may still be handled through a tile URL template. However, for developers building lower-level integrations, proxies, caching layers or custom clients, the OS NGD naming and structure more closely follows the OGC tiling model rather than the older `{z}/{x}/{y}` convention.

***

### Discovery is more explicit in OS NGD API – Tiles

The OS Vector Tile API provides service metadata through:

```
GET https://api.os.uk/maps/vector/v1/vts?srs=3857
```

This returns information such as service name, capabilities, default styles, tile information, extents and related metadata.

OS NGD API – Tiles provides a more granular discovery model. A developer can request the list of available collections:

```
GET https://api.os.uk/maps/vector/ngd/ota/v1/collections
```

The response includes collection identifiers, titles, descriptions, extents, coordinate reference systems and links to related resources.

A developer can also request the available tile matrix sets:

```
GET https://api.os.uk/maps/vector/ngd/ota/v1/tilematrixsets
```

This returns the available tiling schemes and links to their definitions.

This is a meaningful technical difference. With the OS Vector Tile API, developers are more likely to configure against known OS endpoint patterns and documented layer names. With OS NGD API – Tiles, developers can discover the available collections and tiling schemes through the API itself, which is more useful for automated clients, catalogues and standards-based integrations.

***

### Styling moves from a general stylesheet endpoint to collection-specific styles

In the OS Vector Tile API, compatible stylesheets are discovered from a general resource endpoint:

```
GET https://api.os.uk/maps/vector/v1/vts/resources/styles?key={API_KEY}&srs=3857
```

For overlays, the layer name is again inserted into the URL:

```
GET https://api.os.uk/maps/vector/v1/vts/{layer-name}/resources/styles?key={API_KEY}&srs=3857
```

The response follows a familiar style document structure with properties such as `version`, `sprite`, `glyphs`, `sources` and `layers`.

In OS NGD API – Tiles, styles are requested against a collection:

```
GET https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/styles/{styleId}
```

For example:

```
GET https://api.os.uk/maps/vector/ngd/ota/v1/collections/ngd-base/styles/road-38572
```

The OS NGD API – Tiles style endpoint supports style IDs such as `3857`, `27700`, `road-27700`, `road-3857`, `light-27700`, `light-3857`, `blackwhite-27700` and `blackwhite-3857`.

The practical implication is that styles are more closely tied to the collection and projection being used. Developers migrating custom styles should expect to review:

* source names
* source-layer names
* layer IDs
* filter expressions
* min/max zoom behaviour
* sprite and glyph references
* any application logic that assumes OS Vector Tile API layer names

***

### Layer and overlay handling changes

The OS Vector Tile API exposes some overlays as named URL segments, for example:

```
/vts/boundaries/tile/{z}/{y}/{x}.pbf
/vts/greenspace/tile/{z}/{y}/{x}.pbf
/vts/highways/tile/{z}/{y}/{x}.pbf
```

The supported overlay names include `boundaries`, `greenspace`, `sites`, `water`, `highways` and `paths`.

OS NGD API – Tiles instead exposes tile content through collections, for example:

```
/collections/ngd-base/tiles/{tileMatrix}/{tileRow}/{tileCol}
/collections/asu-bdy/tiles/{tileMatrix}/{tileRow}/{tileCol}
/collections/trn-ntwk-railway/tiles/{tileMatrix}/{tileRow}/{tileCol}
```

The documented collection values include `ngd-base`, `asu-bdy`, `wtr-ctch`, `trn-ntwk-railway` and `wtr-tidalboundary`.

This is likely to be one of the more important migration points. A developer cannot assume that an old overlay name maps directly to the same URL structure or source-layer structure in OS NGD API – Tiles. They need to treat OS NGD API – Tiles as a new source schema, even though the client-side rendering model remains similar.

***

### Projection handling changes in the request pattern

The OS Vector Tile API uses the `srs` query parameter to request either British National Grid or Web Mercator tiles. The supported values are `27700` and `3857`, with `27700` used as the default in the technical specification.

OS NGD API – Tiles still supports British National Grid and Web Mercator styles, but the projection is reflected through style IDs such as `road-27700`, `road-3857`, `light-27700` and `light-3857`.

So, for a developer, the migration is not just:

```
Change srs=3857 to srs=27700
```

It is more likely to involve selecting the appropriate collection and style combination, then ensuring the client map projection, tile grid and style source all match.

***

### Authentication is broadly consistent

Both APIs support API key and OAuth2 client credentials authentication. The OS Vector Tile API documentation lists `api-key`, `api-key-header` and `oauth2` as supported authorisation methods, and the OS NGD API – Tiles tile endpoint lists the same authorisation options. 

This means authentication is unlikely to be the most complex part of migration. In many cases, the same OS Data Hub project and credential management approach can be retained, subject to the customer having access to the relevant API.

Example using an API key:

```
GET /maps/vector/ngd/ota/v1/collections/ngd-base/tiles/15/11179/16558 HTTP/1.1
Host: api.os.uk
key: YOUR_API_KEY
Accept: */*
```

Example using OAuth2:

```
GET /maps/vector/ngd/ota/v1/collections/ngd-base/tiles/15/11179/16558 HTTP/1.1
Host: api.os.uk
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
```

The OS NGD API – Tiles documentation shows both API key and OAuth2 bearer token options for tile requests.

## Looking ahead

OS Vector Tile API will continue to be fully supported until its retirement in summer 2028. Existing solutions can continue to use the API until then, although migration is encouraged to provide a more modern standard that is aligned with the wider OS NGD ecosystem

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

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 – Tiles](https://docs.os.uk/os-apis/accessing-os-apis/os-ngd-api-tiles)
  * [What data is available](https://docs.os.uk/os-apis/accessing-os-apis/os-ngd-api-tiles/what-data-is-available) – This page details the OS NGD datasets that were used to create the OS NGD API – Tiles basemap and the OS NGD data that can be uses as an overlay to add additional information.
  * [Getting started](https://docs.os.uk/os-apis/accessing-os-apis/os-ngd-api-tiles/getting-started) – This page provides an overview of how to get started using the OS NGD API – Tiles.


---

# 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-vector-tile-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.