🆕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.
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:
For overlays, the layer name is inserted into the URL:
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:
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:
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:
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:
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:
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:
For overlays, the layer name is again inserted into the URL:
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:
For example:
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:
The supported overlay names include boundaries, greenspace, sites, water, highways and paths.
OS NGD API – Tiles instead exposes tile content through collections, for example:
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:
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:
Example using OAuth2:
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.
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:
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 – This page provides an overview of how to get started using the OS NGD API – Tiles.
Last updated
Was this helpful?