Technical specification

This technical specification explains the content of the OS Vector Tile API and the methods that you can use to call it.

If you are not familiar with the OS Vector Tile API please read the overview documentation before proceeding.

Core concepts

This specification does not cover core concepts that apply to all Ordnance Survey APIs.

Please read the following pages to learn more about OS API core concepts:

• Authentication

• Error codes

• Rate-limiting policy

API reference

OS Vector Tile API has three main endpoints:

• Service metadata

• Styling

• Tile request

OS Vector Tile API is currently available as EPSG:27700 (British National Grid which is applicable just for GB) and EPSG:3857 (Web Mercator which is a global coordinate system). The maps are available as raw information presented using compressed packets of geographic data using the Protocolbuffer Binary Format (.pbf). This provides users optimised maps which render quickly on the web and offer a slick mapping experience.

OS Vector Tile API is currently available as EPSG:27700 (British National Grid which is applicable just for GB) and EPSG:3857 (Web Mercator which is a global coordinate system). The maps are available as raw information presented using compressed packets of geographic data using the Protocolbuffer Binary Format (.pbf). This provides users optimised maps which render quickly on the web and offer a slick mapping experience.

Service Metadata

Service Metadata for OS Vector Tiles API

GEThttps://api.os.uk/maps/vector/v1/vts

Authorization

api-key

Query parameters

Response

200

Retrieves Service Metadata for OS Vector Tiles API

Body

application/json

currentVersionnumber

namestring

capabilitiesstring

typestring

defaultStylesstring

tilesarray of string

exportTilesAllowedboolean

initialExtentExtent (object)

fullExtentExtent (object)

minScalenumber

maxScalenumber

tileInfoTileInfo (object)

maxzoominteger

minLODinteger

maxLODinteger

resourceInfoobject

serviceItemIdstring

maxExportTilesCountinteger

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/maps/vector/v1/vts', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "currentVersion": 0,
  "name": "text",
  "capabilities": "text",
  "type": "text",
  "defaultStyles": "text",
  "tiles": [
    "text"
  ],
  "exportTilesAllowed": false,
  "initialExtent": {
    "xmin": 0,
    "ymin": 0,
    "xmax": 0,
    "ymax": 0,
    "spatialReference": {}
  },
  "fullExtent": {
    "xmin": 0,
    "ymin": 0,
    "xmax": 0,
    "ymax": 0,
    "spatialReference": {}
  },
  "minScale": 0,
  "maxScale": 0,
  "tileInfo": {
    "format": "text",
    "origin": {
      "x": 0,
      "y": 0
    },
    "spatialReference": {
      "xmin": 0,
      "ymin": 0,
      "xmax": 0,
      "ymax": 0,
      "spatialReference": {}
    },
    "lods": [
      {
        "resolution": 0,
        "scale": 0
      }
    ]
  },
  "resourceInfo": {
    "tileCompression": "text",
    "cacheInfo": {
      "storageInfo": {
        "storageFormat": "text"
      }
    }
  },
  "serviceItemId": "text"
}

Styles

Discover compatible stylesheets

GEThttps://api.os.uk/maps/vector/v1/vts/resources/styles

Authorization

api-key

Query parameters

Response

200

Retrieves compatible stylesheets

Body

application/json

version*integer

sprite*string

glyphs*string

sources*object

layers*array of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/maps/vector/v1/vts/resources/styles', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "sprite": "text",
  "glyphs": "text",
  "layers": [
    {
      "id": "text",
      "type": "text",
      "source": "text",
      "source-layer": "text",
      "filter": [
        "text"
      ]
    }
  ]
}

Discover compatible stylesheets for a data overlay

GEThttps://api.os.uk/maps/vector/v1/vts/{layer-name}/resources/styles

Authorization

api-key

Path parameters

layer-name*enum

The name of the data overlay.

boundariesgreenspacesiteswaterhighwayspaths

Query parameters

Response

200

Returns compatible stylesheets for a data overlay.

Body

application/json

version*integer

sprite*string

glyphs*string

sources*object

layers*array of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/maps/vector/v1/vts/{layer-name}/resources/styles', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "sprite": "text",
  "glyphs": "text",
  "layers": [
    {
      "id": "text",
      "type": "text",
      "source": "text",
      "source-layer": "text",
      "filter": [
        "text"
      ]
    }
  ]
}

Tile Request

Access and download data for a specific tile

GEThttps://api.os.uk/maps/vector/v1/vts/tile/{z}/{y}/{x}.pbf

Authorization

api-key

Path parameters

z*integer (int32)

Zoom level

y*integer (int32)

Y coordinate

x*integer (int32)

X coordinate

Query parameters

Response

200

Tile data retrieved successfully

Body

application/octet-stream

string (binary)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/maps/vector/v1/vts/tile/{z}/{y}/{x}.pbf', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

binary

Access and download data for a specific tile from a data overlay

GEThttps://api.os.uk/maps/vector/v1/vts/{layer-name}/tile/{z}/{y}/{x}.pbf

Authorization

api-key

Path parameters

layer-name*enum

The name of the data overlay.

boundariesgreenspacesiteswaterhighwayspaths

z*integer (int32)

Zoom level

y*integer (int32)

Y coordinate

x*integer (int32)

X coordinate

Query parameters

Response

200

Tile data retrieved successfully

Body

application/octet-stream

string (binary)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/maps/vector/v1/vts/{layer-name}/tile/{z}/{y}/{x}.pbf', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

binary