Technical specification

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

The OS Features API lets users call and interact with OS data, including the highly detailed OS MasterMap Topography Layer. It does this by exposing the data through an Open Geospatial Consortium Web Feature Service (OGC WFS).

If you are not familiar with the OS Features 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

The OS Features API exposes data through an Open Geospatial Consortium Web Feature Service (OGC WFS).

The OGC WFS accepts three types of requests:

getCapabilities

Returns a metadata document describing the WFS service provided by the server as well as valid WFS operations and parameters.

GET https://api.os.uk/features/v1/wfs?service=wfs&request=getCapabilities&key=

Required parameters: service

describleFeatureType

Returns a description of the attributes for each feature type supported by the WFS service.

GET https://api.os.uk/features/v1/wfs?service=wfs&version=2.0.0&request=DescribeFeatureType&key=

Required parameters: request, service, version, typeNames

getFeature

Returns a selection of a specific feature from the WFS including its attribute values and geometry. The maximum number of features you can call at any given time is 100.

GET https://api.os.uk/features/v1/wfs?service=wfs&version=2.0.0&request=GetFeature&typeNames=Topography_TopographicPoint&count=20&key=

Required parameters: request, service, version, typeNames

Access to features matching a given query

get

/wfs

Authorizations

Query parameters

requestenumrequired

The type of request being made.

Options: GetCapabilities, DescribeFeatureType, GetFeature

serviceenumrequired

The type of service being requested.

Options: WFS

versionenumrequired

The type of service being requested.

Options: 1.0.0, 1.1.0, 2.0.0

typeNamesenumrequired

The Feature Type being requested.

Options: DetailedPathNetwork_RouteLink, DetailedPathNetwork_RouteNode, Highways_RoadLink, Highways_RoadNode, Highways_FerryLink, Highways_FerryNode, Highways_Street, Highways_ConnectingLink, Highways_ConnectingNode, Highways_PathLink, Highways_PathNode, Greenspace_GreenspaceArea, Sites_AccessPoint, Sites_RoutingPoint, Sites_FunctionalSite, Topography_CartographicText, Topography_CartographicSymbol, Topography_TopographicPoint, Topography_TopographicLine, Topography_TopographicArea, Topography_BoundaryLine, WaterNetwork_HydroNode, WaterNetwork_WatercourseLink, Zoomstack_Airports, Zoomstack_Boundaries, Zoomstack_Contours, Zoomstack_DistrictBuildings, Zoomstack_ETL, Zoomstack_Foreshore, Zoomstack_Greenspace, Zoomstack_LocalBuildings, Zoomstack_Names, Zoomstack_NationalParks, Zoomstack_RailwayStations, Zoomstack_Rail, Zoomstack_RoadsLocal, Zoomstack_RoadsNational, Zoomstack_RoadsRegional, Zoomstack_Sites, Zoomstack_Surfacewater, Zoomstack_UrbanAreas, Zoomstack_Waterlines, Zoomstack_Woodland, OpenUPRN_Address, OpenUSRN_USRN, OpenTOID_TopographyLayer, OpenTOID_HighwaysNetwork, OpenTOID_SitesLayer

bboxstring

A set of valid WFS BBOX coordinates, in the order <bottom-left y, bottom-left x, top-right y, top-right x> (Dependent on CRS)

filterstring

A valid OGC XML filter object

countinteger

An integer stating the maximum number of features to be returned in a single response. In version 1.0.0 and 1.1.0 this is known as maxFeatures

maxFeaturesinteger

An integer stating the maximum number of features to be returned in a single response. In version 2.0.0 this is known as count

sortBystring

Allows the user to order their response based on search attribute.

propertyNamestring

A list of valid feature attribute names, for example, ChangeDate, TOID, PhysicalLevel

startIndexinteger

An integer stating which result to start from, when returning a response

outputFormatenum

The format the response will be returned in. Default: XML.

Options: GML32, GML3, GML2, GEOJSON

resultTypeenum

Type of the results. Default: results.

Options: results, hits

srsNameenum

Allows the user to reproject the selected features into another CRS. Default: EPSG:27700

Options: EPSG:27700, EPSG:4326, EPSG:3857

Responses

application/xmlapplication/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.os.uk/features/v1/wfs?request=GetFeature&service=WFS&version=2.0.0&typeNames=DetailedPathNetwork_RouteLink'

200

200

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "text",
      "geometry": {
        "type": "text",
        "coordinates": [
          {
            "x": 1,
            "y": 1
          }
        ]
      },
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {}
      }
    }
  ]
}

Returns a description of the attributes for each feature type supported by the WFS service.

Access to features matching a given query for a particular year (as an annual snapshot - taking the last full release in the calendar year)

get

/wfs/archive/{year}

Authorizations

Path parameters

yearstringrequired

The year being requested.

Query parameters

requestenumrequired

The type of request being made.

Options: GetCapabilities, DescribeFeatureType, GetFeature

serviceenumrequired

The type of service being requested.

Options: WFS

versionenumrequired

The type of service being requested.

Options: 1.0.0, 1.1.0, 2.0.0

typeNamesenumrequired

The Feature Type being requested.

Options: Highways_RoadLink, Highways_RoadNode, Highways_FerryLink, Highways_FerryNode, Highways_Street, Highways_ConnectingLink, Highways_ConnectingNode, Highways_PathLink, Highways_PathNode, Topography_CartographicText, Topography_CartographicSymbol, Topography_TopographicPoint, Topography_TopographicLine, Topography_TopographicArea, Topography_BoundaryLine, OpenUPRN_Address, ITN_Roads_FerryNode, ITN_Roads_RoadLink, ITN_Roads_RoadNode, ITN_UrbanPaths_ConnectingNode, ITN_UrbanPaths_FerryNode, ITN_UrbanPaths_PathLink, ITN_UrbanPaths_PathNode

bboxstring

A set of valid WFS BBOX coordinates, in the order <bottom-left y, bottom-left x, top-right y, top-right x> (Dependent on CRS)

filterstring

A valid OGC XML filter object

countinteger

An integer stating the maximum number of features to be returned in a single response. In version 1.0.0 and 1.1.0 this is known as maxFeatures

maxFeaturesinteger

An integer stating the maximum number of features to be returned in a single response. In version 2.0.0 this is known as count

sortBystring

Allows the user to order their response based on search attribute.

propertyNamestring

A list of valid feature attribute names, for example, ChangeDate, TOID, PhysicalLevel

startIndexinteger

An integer stating which result to start from, when returning a response

outputFormatenum

The format the response will be returned in. Default: XML.

Options: GML32, GML3, GML2, GEOJSON

resultTypeenum

Type of the results. Default: results.

Options: results, hits

srsNameenum

Allows the user to reproject the selected features into another CRS. Default: EPSG:27700

Options: EPSG:27700, EPSG:4326, EPSG:3857

Responses

application/xmlapplication/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.os.uk/features/v1/wfs/archive/{year}?request=GetFeature&service=WFS&version=2.0.0&typeNames=Highways_RoadLink'

200

200

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "text",
      "geometry": {
        "type": "text",
        "coordinates": [
          {
            "x": 1,
            "y": 1
          }
        ]
      },
      "properties": {
        "ANY_ADDITIONAL_PROPERTY": {}
      }
    }
  ]
}

Returns a description of the attributes for each feature type supported by the WFS service.