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.

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

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/

Response

200400404405406500504

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).

Body

application/json

titleThe title of the API.

While a title is not required, implementors are strongly advised to include one.

Example: "OS NGD API"

descriptionstring

Example: "Ordnance Survey National Geographic Database API."

attributionattribution for the API

The attribution should be short and intended for presentation to a user, for example, in a corner of a map. Parts of the text can be links to other resources if additional information is needed. The string can include HTML markup.

links*array of link (object)

Request

JavaScriptCurlPython

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

Response

200400404405406500504

{
  "title": "OS NGD API",
  "description": "Ordnance Survey National Geographic Database API.",
  "attribution": "text",
  "links": [
    {
      "href": "http://data.example.com/buildingpart/123",
      "rel": "alternate",
      "type": "application/geo+json",
      "templated": false,
      "varBase": "/ogcapi/vars/",
      "hreflang": "en",
      "title": "Building Part",
      "length": 0
    }
  ]
}

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

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/conformance

Response

200400404405406500504

The URIs of all conformance classes supported by the server

Body

application/json

conformsTo*array of string

Request

JavaScriptCurlPython

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

Response

200400404405406500504

{
  "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"
  ]
}

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

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/collections

Response

200400404405406500504

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').

Body

application/jsontext/html

links*array of link (object)

collections*array of collectionInfo (object)

Request

JavaScriptCurlPython

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

Response

200400404405406500504

{
  "links": [
    {
      "href": "http://data.example.com/buildingpart/123",
      "rel": "alternate",
      "type": "application/geo+json",
      "templated": false,
      "varBase": "/ogcapi/vars/",
      "hreflang": "en",
      "title": "Building Part",
      "length": 0
    }
  ],
  "collections": [
    {
      "id": "buildingpart",
      "title": "Building Part",
      "description": "Polygon feature representing a building.",
      "links": [
        {
          "href": "http://data.example.org/collections/buildingpart",
          "rel": "self",
          "type": "application/json",
          "title": "Building Part"
        }
      ],
      "extent": {
        "spatial": {
          "bbox": [
            [
              -180,
              -90,
              180,
              90
            ]
          ],
          "crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
        }
      }
    }
  ]
}

Retrieve the description of a collection available from this service.

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}

Path parameters

collectionId*AllCollections (enum)

Local identifier of a collection

ngd-baseasu-bdywtr-ctchtrn-ntwk-railway

Response

200400404405406500504

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').

Body

application/json

id*string

identifier of the collection used, for example, in URIs

Example: "buildingpart"

titlestring

human readable title of the collection

Example: "Building Part"

descriptionstring

a description of the data in the collection

Example: "Polygon feature representing a building."

links*array of link (object)

extentExtent with Uniform Additional Dimensions Schema

The extent module only addresses spatial and temporal extents. This module extends extent by specifying how intervals and crs properties can be used to specify additional geometries.

Request

JavaScriptCurlPython

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

Response

200400404405406500504

{
  "id": "buildingpart",
  "title": "Building Part",
  "description": "Polygon feature representing a building.",
  "links": [
    {
      "href": "http://data.example.org/collections/buildingpart",
      "rel": "self",
      "type": "application/json",
      "title": "Building Part"
    }
  ],
  "extent": {
    "spatial": {
      "bbox": [
        [
          -180,
          -90,
          180,
          90
        ]
      ],
      "crs": "http://www.opengis.net/def/crs/EPSG/0/3857"
    }
  }
}

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

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/tilematrixsets

Response

200400404405406500504

List of tile matrix sets (tiling schemes).

Body

application/json

tileMatrixSetsarray of Tile Matrix Set Item

Request

JavaScriptCurlPython

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

Response

200400404405406500504

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

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

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/tilematrixsets/{tileMatrixSetId}

Path parameters

tileMatrixSetId*TileMatrixSets (enum)

Identifier for a supported TileMatrixSet

385727700

Response

200400404405406500504

tile matrix set

Body

application/json

titlestring

Title of this tile matrix set, normally used for display to a human

idstring

Tile matrix set identifier. Implementation of 'identifier'

uristring (uri)

Reference to an official source for this tileMatrixSet

orderedAxesarray of string

crs*all of

wellKnownScaleSetstring (uri)

Reference to a well-known scale set

tileMatrices*array of tileMatrix (object)

Describes scale levels and its tile matrices

Request

JavaScriptCurlPython

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

Response

200400404405406500504

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

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

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles

Path parameters

collectionId*AllCollections (enum)

Local identifier of a collection

ngd-baseasu-bdywtr-ctchtrn-ntwk-railway

Response

200400404405406500504

List of available tilesets.

Body

application/json

linksarray of link (object)

tilesets*array of Tile Set Metadata item

Request

JavaScriptCurlPython

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

Response

200400404405406500504

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

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

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles/{tileMatrixSetId}

Path parameters

collectionId*AllCollections (enum)

Local identifier of a collection

ngd-baseasu-bdywtr-ctchtrn-ntwk-railway

tileMatrixSetId*TileSets (enum)

Identifier for a supported TileMatrixSet

385727700

Response

200400404405406500504

Description of the tileset

Body

application/json

idstring

identifier of the tile matrix set

Example: "3857"

titlestring

A title for this tileset

dataType*all of

crs*all of

tileMatrixSetURIstring (uri)

Reference to a Tile Matrix Set on an offical source for Tile Matrix Sets such as the OGC NA definition server (http://www.opengis.net/def/tms/). Required if the tile matrix set is registered on an open official source.

links*array of link (object)

Links to related resources. A 'self' link to the tileset as well as a 'http://www.opengis.net/def/rel/ogc/1.0/tiling-scheme' link to a definition of the TileMatrixSet are required.

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles/{tileMatrixSetId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400404405406500504

{
  "description": "text",
  "tileMatrixSetLimits": [
    {
      "tileMatrix": "text",
      "minTileRow": 0,
      "maxTileRow": 0,
      "minTileCol": 0,
      "maxTileCol": 0
    }
  ],
  "layers": [
    {
      "description": "text",
      "id": "text",
      "dataType": {},
      "geometryType": "text",
      "maxTileMatrix": "text",
      "minTileMatrix": "text",
      "propertiesSchema": {
        "type": "object"
      }
    }
  ],
  "boundingBox": {
    "lowerLeft": [
      0
    ],
    "upperRight": [
      0
    ],
    "crs": "https://example.com"
  }
}

Retrieve a vector tile from a collection.

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}

Authorization

api-key

Path parameters

tileMatrix*string

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

Example: "15"

tileRow*integer

Row index of the tile on the selected TileMatrix.

Example: 11179

tileCol*integer

Column index of the tile on the selected TileMatrix.

Example: 16558

collectionId*AllCollections (enum)

Local identifier of a collection

ngd-baseasu-bdywtr-ctchtrn-ntwk-railway

tileMatrixSetId*TileSets (enum)

Identifier for a supported TileMatrixSet

385727700

Response

200400404405406500504

A vector tile returned as a response.

Body

application/octet-stream

string (binary)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400404405406500504

binary

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

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles/{tileMatrix}/{tileRow}/{tileCol}

Authorization

api-key

Path parameters

tileMatrix*string

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

Example: "15"

tileRow*integer

Row index of the tile on the selected TileMatrix.

Example: 11179

tileCol*integer

Column index of the tile on the selected TileMatrix.

Example: 16558

collectionId*AllCollections (enum)

Local identifier of a collection

ngd-baseasu-bdywtr-ctchtrn-ntwk-railway

Response

200400404405406500504

A vector tile returned as a response.

Body

application/octet-stream

string (binary)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/tiles/{tileMatrix}/{tileRow}/{tileCol}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400404405406500504

binary

Retrieve the list of styles available from this service.

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/styles

Path parameters

collectionId*AllCollections (enum)

Local identifier of a collection

ngd-baseasu-bdywtr-ctchtrn-ntwk-railway

Response

200400404405406500504

List of available styles.

Body

application/json

linksarray of link (object)

styles*array of style-item (object)

Request

JavaScriptCurlPython

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

Response

200400404405406500504

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

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.

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

Path parameters

collectionId*AllCollections (enum)

Local identifier of a collection

ngd-baseasu-bdywtr-ctchtrn-ntwk-railway

styleId*Styles (enum)

An identifier representing a specific style.

385727700

Response

200400404405406500504

OK

Body

*/*

object

Request

JavaScriptCurlPython

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

Response

400404405406500504

{
  "type": "text",
  "title": "text",
  "status": 0,
  "detail": "text",
  "instance": "text",
  "code": 0,
  "description": "text",
  "help": "text"
}

Styling resources such as fonts and sprites

GEThttps://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/styles/{styleId}/{resourceBaseName}/**

Path parameters

collectionId*AllCollections (enum)

Local identifier of a collection

ngd-baseasu-bdywtr-ctchtrn-ntwk-railway

styleId*Styles (enum)

An identifier representing a specific style.

385727700

resourceBaseName*string

Styling resourece base name.

Example: "sprites"

Response

200400404405406500504

OK

Body

*/*

object

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/maps/vector/ngd/ota/v1/collections/{collectionId}/styles/{styleId}/{resourceBaseName}/**', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

400404405406500504

{
  "type": "text",
  "title": "text",
  "status": 0,
  "detail": "text",
  "instance": "text",
  "code": 0,
  "description": "text",
  "help": "text"
}