OS Docs Home OS APIs OS Download Products More than Maps OS Data Hub FAQs

Technical Specification

OS NGD API – Tiles 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. Click into each endpoint to learn more.

PreviousWhat data is available?NextGetting Started

Last updated 4 months ago

Was this helpful?

Retrieve the OS NGD API – Tiles landing page for this service.

get

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/'

200

400

404

405

406

500

504

{
  "title": "OS NGD API",
  "description": "Ordnance Survey National Geographic Database API",
  "links": [
    {
      "href": "http://data.example.org/",
      "rel": "self",
      "type": "application/json",
      "title": "this document"
    },
    {
      "href": "http://data.example.org/api?f=json",
      "rel": "service-desc",
      "type": "application/vnd.oai.openapi+json;version=3.0",
      "title": "the API definition"
    },
    {
      "href": "http://data.example.org/api",
      "rel": "service-doc",
      "type": "text/html",
      "title": "the API documentation"
    },
    {
      "href": "http://data.example.org/conformance",
      "rel": "conformance",
      "type": "application/json",
      "title": "OGC API conformance classes implemented by this service"
    },
    {
      "href": "http://data.example.org/collections",
      "rel": "data",
      "type": "application/json",
      "title": "Information about the collections"
    }
  ]
}

The landing page provides links to the API definition (link relation service-desc, in this case path /api), to the Conformance declaration (path /conformance, link relation conformance), and to the Collections of geospatial data (path /collections, link relation data).

Retrieve the set of OS NGD API – Tiles conformance classes that are supported by this service.

get

/conformance

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/conformance'

200

400

404

405

406

500

504

{
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core",
    "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/json",
    "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/html",
    "http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/oas30",
    "http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/collections",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/core",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/tileset",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/tilesets-list",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/geodata-tilesets",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/dataset-tilesets",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/geodata-selection",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/jpeg",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/png",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/mvt",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/geojson",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/tiff",
    "http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/netcdf"
  ]
}

The URIs of all conformance classes supported by the server

Retrieve the list of geospatial data collections available from this service.

get

/collections

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/collections'

200

400

404

405

406

500

504

{
  "links": [
    {
      "href": "http://data.example.org/collections",
      "rel": "self",
      "type": "application/json",
      "title": "All collections"
    }
  ],
  "collections": [
    {
      "id": "buildingpart",
      "title": "Building Part",
      "description": "Polygon feature representing a building.",
      "links": [
        {
          "href": "http://data.example.org/collections/buildingpart/items",
          "rel": "items",
          "type": "application/geo+json",
          "title": "Building Part"
        }
      ],
      "extent": {
        "spatial": {
          "bbox": [
            [
              -8.82,
              49.79,
              1.92,
              60.94
            ]
          ]
        },
        "temporal": {
          "interval": [
            [
              "2022-08-27T00:00:00Z",
              null
            ]
          ]
        }
      },
      "x-description-html": "<p>Polygon feature representing a building.</p>"
    }
  ]
}

The collections of (mostly geospatial) data available from this API. The dataset contains one or more collections. This resource provides information about and access to the collections. The response contains the list of collections. Each collection is accessible via one or more OGC API set of specifications, for which a link to relevant accessible resources, e.g. /collections/{collectionId}/(items, coverage, map, tiles...) is provided, with the corresponding relation type, as well as key information about the collection. This information includes:

a local identifier for the collection that is unique for the dataset;
a list of coordinate reference systems (CRS) in which data may be returned by the server. The first CRS is the default coordinate reference system (the default is always WGS 84 with axis order longitude/latitude);
an optional title and description for the collection;
an optional extent that can be used to provide an indication of the spatial and temporal extent of the collection - typically derived from the data;
for collections accessible via the Features or Records API, an optional indicator about the type of the items in the collection (the default value, if the indicator is not provided, is 'feature').

Retrieve the description of a collection available from this service.

get

/collections/{collectionId}

Path parameters

collectionIdenumrequired

Local identifier of a collection

Options: ngd-base, asu-bdy, wtr-ctch, trn-ntwk-railway

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}'

200

400

404

405

406

500

504

{
  "id": "buildingpart",
  "title": "Building Part",
  "description": "Polygon feature representing a building.",
  "links": [
    {
      "href": "http://data.example.org/collections/buildingpart/items",
      "rel": "items",
      "type": "application/geo+json",
      "title": "Building Part"
    }
  ],
  "extent": {
    "spatial": {
      "bbox": [
        [
          -8.82,
          49.79,
          1.92,
          60.94
        ]
      ]
    },
    "temporal": {
      "interval": [
        [
          "2022-08-27T00:00:00Z",
          null
        ]
      ]
    }
  }
}

Information about a particular collection of (mostly geospatial) data available from this API. The collection is accessible via one or more OGC API set of specifications, for which a link to relevant accessible resources, e.g. /collections/{collectionId}/(items, coverage, map, tiles...) is contained in the response, with the corresponding relation type, as well as key information about the collection. This information includes:

a local identifier for the collection that is unique for the dataset;
a list of coordinate reference systems (CRS) in which data may be returned by the server. The first CRS is the default coordinate reference system (the default is always WGS 84 with axis order longitude/latitude);
an optional title and description for the collection;
an optional extent that can be used to provide an indication of the spatial and temporal extent of the collection - typically derived from the data;
for collections accessible via the Features or Records API, an optional indicator about the type of the items in the collection (the default value, if the indicator is not provided, is 'feature').

Retrieve the list of available tiling schemes (tile matrix sets)

get

/tilematrixsets

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/tilematrixsets'

200

400

404

405

406

500

504

{
  "tileMatrixSets": [
    {
      "id": "text",
      "title": "text",
      "uri": "https://example.com",
      "links": [
        {
          "length": 1,
          "href": "http://data.example.com/buildingpart/123",
          "rel": "alternate",
          "type": "application/geo+json",
          "templated": true,
          "varBase": "/ogcapi/vars/",
          "hreflang": "en",
          "title": "Building Part"
        }
      ],
      "crs": "https://example.com"
    }
  ]
}

List of tile matrix sets (tiling schemes).

Retrieve the definition of the specified tiling scheme (tile matrix set)

get

/tilematrixsets/{tileMatrixSetId}

Path parameters

tileMatrixSetIdenumrequired

Identifier for a supported TileMatrixSet

Options: 3857, 27700

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/tilematrixsets/{tileMatrixSetId}'

200

400

404

405

406

500

504

{
  "title": "text",
  "id": "text",
  "uri": "https://example.com",
  "wellKnownScaleSet": "https://example.com",
  "orderedAxes": [
    "text"
  ],
  "crs": "https://example.com",
  "tileMatrices": [
    {
      "id": "text",
      "scaleDenominator": 1,
      "cellSize": 1,
      "tileWidth": 1,
      "tileHeight": 1,
      "matrixHeight": 1,
      "matrixWidth": 1,
      "cornerOfOrigin": "topLeft",
      "pointOfOrigin": [
        1
      ]
    }
  ]
}

tile matrix set

Retrieve a list of available vector tilesets for the specified collection.

get

/collections/{collectionId}/tiles

Path parameters

collectionIdenumrequired

Local identifier of a collection

Options: ngd-base, asu-bdy, wtr-ctch, trn-ntwk-railway

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles'

200

400

404

405

406

500

504

{
  "links": [
    {
      "length": 1,
      "href": "http://data.example.com/buildingpart/123",
      "rel": "alternate",
      "type": "application/geo+json",
      "templated": true,
      "varBase": "/ogcapi/vars/",
      "hreflang": "en",
      "title": "Building Part"
    }
  ],
  "tilesets": [
    {
      "id": "3857",
      "title": "text",
      "tileMatrixSetURI": "https://example.com",
      "dataType": "map",
      "crs": "https://example.com",
      "links": [
        {
          "length": 1,
          "href": "http://data.example.com/buildingpart/123",
          "rel": "alternate",
          "type": "application/geo+json",
          "templated": true,
          "varBase": "/ogcapi/vars/",
          "hreflang": "en",
          "title": "Building Part"
        }
      ]
    }
  ]
}

List of available tilesets.

Retrieve the vector tileset metadata for the specified collection and tiling scheme (tile matrix set)

get

/collections/{collectionId}/tiles/{tileMatrixSetId}

Path parameters

collectionIdenumrequired

Local identifier of a collection

Options: ngd-base, asu-bdy, wtr-ctch, trn-ntwk-railway

tileMatrixSetIdenumrequired

Identifier for a supported TileMatrixSet

Options: 3857, 27700

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles/{tileMatrixSetId}'

200

400

404

405

406

500

504

{
  "description": "text",
  "layers": [
    {
      "geometryType": "text",
      "propertiesSchema": {
        "type": "object",
        "properties": {}
      },
      "description": "text",
      "id": "text",
      "maxTileMatrix": "text",
      "minTileMatrix": "text",
      "dataType": "map"
    }
  ],
  "boundingBox": {
    "crs": "https://example.com",
    "lowerLeft": [
      1
    ],
    "upperRight": [
      1
    ]
  },
  "tileMatrixSetLimits": [
    {
      "tileMatrix": "text",
      "minTileRow": 1,
      "maxTileRow": 1,
      "minTileCol": 1,
      "maxTileCol": 1
    }
  ],
  "id": "3857",
  "title": "text",
  "tileMatrixSetURI": "https://example.com",
  "dataType": "map",
  "crs": "https://example.com",
  "links": [
    {
      "length": 1,
      "href": "http://data.example.com/buildingpart/123",
      "rel": "alternate",
      "type": "application/geo+json",
      "templated": true,
      "varBase": "/ogcapi/vars/",
      "hreflang": "en",
      "title": "Building Part"
    }
  ]
}

Description of the tileset

Retrieve a vector tile from a collection.

get

/collections/{collectionId}/tiles/{tileMatrixSetId}//{tileMatrix}//{tileRow}//{tileCol}

Authorizations

Path parameters

tileMatrixstringrequired

Identifier selecting one of the scales defined in the TileMatrixSet and representing the scaleDenominator the tile.

Example: 15

tileRowintegerrequired

Row index of the tile on the selected TileMatrix.

Example: 11179

tileColintegerrequired

Column index of the tile on the selected TileMatrix.

Example: 16558

collectionIdenumrequired

Local identifier of a collection

Options: ngd-base, asu-bdy, wtr-ctch, trn-ntwk-railway

tileMatrixSetIdenumrequired

Identifier for a supported TileMatrixSet

Options: 3857, 27700

Responses

application/octet-stream

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}'

200

400

404

405

406

500

504

text

A vector tile returned as a response.

Retrieve a vector tile from a collection for Web Mercator Quad EPSG: 3857 tile matrix set.

get

/collections/{collectionId}/tiles/{tileMatrix}//{tileRow}//{tileCol}

Authorizations

Path parameters

tileMatrixstringrequired

Identifier selecting one of the scales defined in the TileMatrixSet and representing the scaleDenominator the tile.

Example: 15

tileRowintegerrequired

Row index of the tile on the selected TileMatrix.

Example: 11179

tileColintegerrequired

Column index of the tile on the selected TileMatrix.

Example: 16558

collectionIdenumrequired

Local identifier of a collection

Options: ngd-base, asu-bdy, wtr-ctch, trn-ntwk-railway

Responses

application/octet-stream

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles/{tileMatrix}/{tileRow}/{tileCol}'

200

400

404

405

406

500

504

text

A vector tile returned as a response.

Retrieve the list of styles available from this service.

get

/collections/{collectionId}/styles

Path parameters

collectionIdenumrequired

Local identifier of a collection

Options: ngd-base, asu-bdy, wtr-ctch, trn-ntwk-railway

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/styles'

200

400

404

405

406

500

504

{
  "links": [
    {
      "length": 1,
      "href": "http://data.example.com/buildingpart/123",
      "rel": "alternate",
      "type": "application/geo+json",
      "templated": true,
      "varBase": "/ogcapi/vars/",
      "hreflang": "en",
      "title": "Building Part"
    }
  ],
  "styles": [
    {
      "id": "text",
      "title": "text",
      "links": [
        {
          "length": 1,
          "href": "http://data.example.com/buildingpart/123",
          "rel": "alternate",
          "type": "application/geo+json",
          "templated": true,
          "varBase": "/ogcapi/vars/",
          "hreflang": "en",
          "title": "Building Part"
        }
      ]
    }
  ]
}

List of available styles.

Root level properties of a style specify the map's layers, tile sources and other resources, and default values for the initial camera position when not specified elsewhere.

get

/collections/{collectionId}/styles/{styleId}

Path parameters

collectionIdenumrequired

Local identifier of a collection

Options: ngd-base, asu-bdy, wtr-ctch, trn-ntwk-railway

styleIdenumrequired

An identifier representing a specific style.

Options: 3857, 27700

Responses

*/*

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/styles/{styleId}'

200

400

404

405

406

500

504

{}

Styling resources such as fonts and sprites

get

/collections/{collectionId}/styles/{styleId}//{resourceBaseName}/**

Path parameters

collectionIdenumrequired

Local identifier of a collection

Options: ngd-base, asu-bdy, wtr-ctch, trn-ntwk-railway

styleIdenumrequired

An identifier representing a specific style.

Options: 3857, 27700

resourceBaseNamestringrequired

Styling resourece base name.

Example: sprites

Responses

*/*

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/styles/{styleId}/{resourceBaseName}/**'

200

400

404

405

406

500

504

{}