Ordnance Survey Features API

openapi: 3.2.0
info:
  title: OS NGD Features API
  version: v1.8.1
  description: Retrieve features
servers:
- url: https://api.os.uk/features/ngd/ofa/v1
tags:
- name: Features
  description: Retrieve features
paths:
  /collections/{collectionId}/items:
    get:
      security:
      - api-key: []
        api-key-header: []
        oauth2: []
      tags:
      - Features
      summary: Retrieve features in the feature collection
      operationId: getItems
      parameters:
      - name: collectionId
        in: path
        description: A known collection ID.
        required: true
        schema:
          type: string
          enum:
          - asu-gbpcd-postcodeunitarea-1
          - asu-gbpcd-postcodeunitpoint-1
          - bld-fts-building-1
          - bld-fts-building-2
          - bld-fts-building-3
          - bld-fts-building-4
          - bld-fts-buildingaccesslocation-1
          - bld-fts-buildingline-1
          - bld-fts-buildingpart-1
          - bld-fts-buildingpart-2
          - gnm-fts-crowdsourcednamepoint-1
          - gnm-fts-namedarea-1
          - gnm-fts-namedpoint-1
          - gnm-fts-namedroadjunction-1
          - lnd-fts-land-1
          - lnd-fts-land-2
          - lnd-fts-land-3
          - lnd-fts-landform-1
          - lnd-fts-landformline-1
          - lnd-fts-landformpoint-1
          - lnd-fts-landpoint-1
          - lus-fts-site-1
          - lus-fts-site-2
          - lus-fts-siteaccesslocation-1
          - lus-fts-siteaccesslocation-2
          - lus-fts-siteroutingpoint-1
          - str-fts-compoundstructure-1
          - str-fts-compoundstructure-2
          - str-fts-compoundstructure-3
          - str-fts-fieldboundary-1
          - str-fts-structure-1
          - str-fts-structure-2
          - str-fts-structure-3
          - str-fts-structureline-1
          - str-fts-structurepoint-1
          - trn-fts-cartographicraildetail-1
          - trn-fts-rail-1
          - trn-fts-rail-2
          - trn-fts-rail-3
          - trn-fts-roadline-1
          - trn-fts-roadtrackorpath-1
          - trn-fts-roadtrackorpath-2
          - trn-fts-roadtrackorpath-3
          - trn-fts-streetlight-1
          - trn-ntwk-buslane-1
          - trn-ntwk-connectinglink-1
          - trn-ntwk-connectingnode-1
          - trn-ntwk-cyclelane-1
          - trn-ntwk-ferrylink-1
          - trn-ntwk-ferrynode-1
          - trn-ntwk-ferryterminal-1
          - trn-ntwk-path-1
          - trn-ntwk-pathlink-1
          - trn-ntwk-pathlink-2
          - trn-ntwk-pathlink-3
          - trn-ntwk-pathnode-1
          - trn-ntwk-pavementlink-1
          - trn-ntwk-railwaylink-1
          - trn-ntwk-railwaylinkset-1
          - trn-ntwk-railwaynode-1
          - trn-ntwk-road-1
          - trn-ntwk-roadjunction-1
          - trn-ntwk-roadlink-1
          - trn-ntwk-roadlink-2
          - trn-ntwk-roadlink-3
          - trn-ntwk-roadlink-4
          - trn-ntwk-roadlink-5
          - trn-ntwk-roadnode-1
          - trn-ntwk-street-1
          - trn-ntwk-tramonroad-1
          - trn-rami-averageandindicativespeed-1
          - trn-rami-highwaydedication-1
          - trn-rami-maintenancearea-1
          - trn-rami-maintenanceline-1
          - trn-rami-maintenancepoint-1
          - trn-rami-reinstatementarea-1
          - trn-rami-reinstatementline-1
          - trn-rami-reinstatementpoint-1
          - trn-rami-restriction-1
          - trn-rami-routinghazard-1
          - trn-rami-routingstructure-1
          - trn-rami-specialdesignationarea-1
          - trn-rami-specialdesignationline-1
          - trn-rami-specialdesignationpoint-1
          - wtr-fts-intertidalline-1
          - wtr-fts-tidalboundary-1
          - wtr-fts-water-1
          - wtr-fts-water-2
          - wtr-fts-water-3
          - wtr-fts-waterpoint-1
          - wtr-ntwk-waterlink-1
          - wtr-ntwk-waterlink-2
          - wtr-ntwk-waterlinkset-1
          - wtr-ntwk-waternode-1
        example: asu-gbpcd-postcodeunitarea-1
      - name: bbox
        in: query
        description: 'The optional bbox parameter specifies a supported bounding box. Only features that have a geometry that intersects the bounding box are selected. The bounding box is provided as four comma-separated numbers:  <ul><li>Lower left corner, coordinate axis 1 (e.g. min x axis)</li><li> Lower left corner, coordinate axis 2 (e.g. min y axis)</li><li> Upper right corner, coordinate axis 1 (e.g. max x axis)</li><li> Upper right corner, coordinate axis 2 (e.g. max y axis)</li></ul>The default coordinate reference system of the values is WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate reference system is specified in the parameter `bbox-crs`.'
        style: form
        explode: false
        schema:
          maxItems: 6
          minItems: 4
          type: array
          items:
            type: number
        example:
        - -0.183678
        - 51.474968
        - -0.068321
        - 51.540143
      - name: bbox-crs
        in: query
        description: The coordinate reference system of the `bbox` parameter. It must be a 2D coordinate reference system supported by the collection. Default is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).
        schema:
          type: string
          enum:
          - http://www.opengis.net/def/crs/OGC/1.3/CRS84
          - http://www.opengis.net/def/crs/EPSG/0/27700
          - http://www.opengis.net/def/crs/EPSG/0/4326
          - http://www.opengis.net/def/crs/EPSG/0/3857
      - name: crs
        in: query
        description: The coordinate reference system of the response geometries. It must be a coordinate reference system supported by the collection. Default is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).
        schema:
          type: string
          enum:
          - http://www.opengis.net/def/crs/OGC/1.3/CRS84
          - http://www.opengis.net/def/crs/EPSG/0/27700
          - http://www.opengis.net/def/crs/EPSG/0/4326
          - http://www.opengis.net/def/crs/EPSG/0/3857
          - http://www.opengis.net/def/crs/EPSG/0/7405
      - name: datetime
        in: query
        description: 'Either a local date, a date-time with UTC time zone (Z) or an open or closed interval. Open ranges in time intervals at the start or end are supported using a double-dot (..) or an empty string for the start/end. Date and time expressions adhere to RFC 3339. Examples:<ul><li>A date-time: ''2021-12-12T23:20:50Z''</li><li>A closed interval: ''2021-12-12T00:00:00Z/2021-12-18T12:31:12Z''</li><li>Open intervals: ''2021-12-12T00:00:00Z/..'' or ''../2021-12-18T12:31:12Z''</li><li>An interval until now: ''2018-02-12T00:00:00Z/..'' or ''2018-02-12T00:00:00Z/''</li></ul>Selects features that have a temporal property that intersects the value of the parameter.'
        style: form
        schema:
          type: string
        example: 2018-02-12T00:00:00Z/..
      - name: limit
        in: query
        description: The optional limit parameter limits the number of items that are presented in the response document. Minimum = 1. Maximum = 100. Default = 100.
        style: form
        schema:
          maximum: 100
          minimum: 1
          type: integer
      - name: offset
        in: query
        description: The optional offset parameter skips past the specified number of features in the collection. Minimum = 0. Default = 0.
        schema:
          minimum: 0
          type: integer
      - name: filter
        in: query
        description: The optional filter parameter is a filter expression in CQL format which is applied when retrieving resources to determine which resources are included in a result set.
        schema:
          type: string
      - name: filter-crs
        in: query
        description: Specify which of the supported CRSs to use to encode geometric values in a filter expression. It must be a 2D coordinate reference system supported by the collection. Default is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).
        schema:
          type: string
          enum:
          - http://www.opengis.net/def/crs/OGC/1.3/CRS84
          - http://www.opengis.net/def/crs/EPSG/0/27700
          - http://www.opengis.net/def/crs/EPSG/0/4326
          - http://www.opengis.net/def/crs/EPSG/0/3857
      - name: filter-lang
        in: query
        description: The optional filter-lang parameter is the specific language used for the filter parameter. Default = cql-text
        schema:
          type: string
          enum:
          - cql-text
      responses:
        '200':
          description: A list of features in a feature collection.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/FeatureCollectionResponse'
        '400':
          description: The items request is not supported. Please refer to documentation for examples.
        '404':
          description: Collection '{collectionId}' is not a supported Collection. Please refer to the documentation for a list of supported Collections.
        '405':
          description: The HTTP method requested is not supported. This endpoint only supports 'GET' requests.
        '406':
          description: A request header value was not supported.
        '504':
          description: 'The request has timed out. Please check the service availability dashboard: https://osdatahub.os.uk/serviceStatus .'
  /collections/{collectionId}/items/{featureId}:
    get:
      security:
      - api-key: []
        api-key-header: []
        oauth2: []
      tags:
      - Features
      summary: Retrieve a feature from the feature collection
      operationId: getItemById
      parameters:
      - name: collectionId
        in: path
        description: A known collection ID.
        required: true
        schema:
          type: string
          enum:
          - asu-gbpcd-postcodeunitarea-1
          - asu-gbpcd-postcodeunitpoint-1
          - bld-fts-building-1
          - bld-fts-building-2
          - bld-fts-building-3
          - bld-fts-building-4
          - bld-fts-buildingaccesslocation-1
          - bld-fts-buildingline-1
          - bld-fts-buildingpart-1
          - bld-fts-buildingpart-2
          - gnm-fts-crowdsourcednamepoint-1
          - gnm-fts-namedarea-1
          - gnm-fts-namedpoint-1
          - gnm-fts-namedroadjunction-1
          - lnd-fts-land-1
          - lnd-fts-land-2
          - lnd-fts-land-3
          - lnd-fts-landform-1
          - lnd-fts-landformline-1
          - lnd-fts-landformpoint-1
          - lnd-fts-landpoint-1
          - lus-fts-site-1
          - lus-fts-site-2
          - lus-fts-siteaccesslocation-1
          - lus-fts-siteaccesslocation-2
          - lus-fts-siteroutingpoint-1
          - str-fts-compoundstructure-1
          - str-fts-compoundstructure-2
          - str-fts-compoundstructure-3
          - str-fts-fieldboundary-1
          - str-fts-structure-1
          - str-fts-structure-2
          - str-fts-structure-3
          - str-fts-structureline-1
          - str-fts-structurepoint-1
          - trn-fts-cartographicraildetail-1
          - trn-fts-rail-1
          - trn-fts-rail-2
          - trn-fts-rail-3
          - trn-fts-roadline-1
          - trn-fts-roadtrackorpath-1
          - trn-fts-roadtrackorpath-2
          - trn-fts-roadtrackorpath-3
          - trn-fts-streetlight-1
          - trn-ntwk-buslane-1
          - trn-ntwk-connectinglink-1
          - trn-ntwk-connectingnode-1
          - trn-ntwk-cyclelane-1
          - trn-ntwk-ferrylink-1
          - trn-ntwk-ferrynode-1
          - trn-ntwk-ferryterminal-1
          - trn-ntwk-path-1
          - trn-ntwk-pathlink-1
          - trn-ntwk-pathlink-2
          - trn-ntwk-pathlink-3
          - trn-ntwk-pathnode-1
          - trn-ntwk-pavementlink-1
          - trn-ntwk-railwaylink-1
          - trn-ntwk-railwaylinkset-1
          - trn-ntwk-railwaynode-1
          - trn-ntwk-road-1
          - trn-ntwk-roadjunction-1
          - trn-ntwk-roadlink-1
          - trn-ntwk-roadlink-2
          - trn-ntwk-roadlink-3
          - trn-ntwk-roadlink-4
          - trn-ntwk-roadlink-5
          - trn-ntwk-roadnode-1
          - trn-ntwk-street-1
          - trn-ntwk-tramonroad-1
          - trn-rami-averageandindicativespeed-1
          - trn-rami-highwaydedication-1
          - trn-rami-maintenancearea-1
          - trn-rami-maintenanceline-1
          - trn-rami-maintenancepoint-1
          - trn-rami-reinstatementarea-1
          - trn-rami-reinstatementline-1
          - trn-rami-reinstatementpoint-1
          - trn-rami-restriction-1
          - trn-rami-routinghazard-1
          - trn-rami-routingstructure-1
          - trn-rami-specialdesignationarea-1
          - trn-rami-specialdesignationline-1
          - trn-rami-specialdesignationpoint-1
          - wtr-fts-intertidalline-1
          - wtr-fts-tidalboundary-1
          - wtr-fts-water-1
          - wtr-fts-water-2
          - wtr-fts-water-3
          - wtr-fts-waterpoint-1
          - wtr-ntwk-waterlink-1
          - wtr-ntwk-waterlink-2
          - wtr-ntwk-waterlinkset-1
          - wtr-ntwk-waternode-1
        example: asu-gbpcd-postcodeunitarea-1
      - name: featureId
        in: path
        description: A feature ID which is the identifier(id) for the feature.
        required: true
        schema:
          type: string
        example: 11111111-1111-1111-1111-111111111111
      - name: crs
        in: query
        description: The coordinate reference system of the response geometries. It must be a coordinate reference system supported by the collection. Default is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84).
        schema:
          type: string
          enum:
          - http://www.opengis.net/def/crs/OGC/1.3/CRS84
          - http://www.opengis.net/def/crs/EPSG/0/27700
          - http://www.opengis.net/def/crs/EPSG/0/4326
          - http://www.opengis.net/def/crs/EPSG/0/3857
          - http://www.opengis.net/def/crs/EPSG/0/7405
      responses:
        '200':
          description: A single feature in the feature collection.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/Feature'
        '400':
          description: The feature request contains elements that are not supported. Please refer to documentation for examples.
        '404':
          description: The feature collection '{collectionId}' or feature with id:'{featureId}' could not be found. Please check it is a supported collection or feature.
        '405':
          description: The HTTP method requested is not supported. This endpoint only supports 'GET' requests.
        '406':
          description: A request header value was not supported.
        '504':
          description: 'The request has timed out. Please check the service availability dashboard: https://osdatahub.os.uk/serviceStatus .'
components:
  schemas:
    Link:
      type: object
      properties:
        href:
          type: string
          format: url
        rel:
          type: string
        type:
          type: string
        title:
          type: string
    Geometry:
      type: object
      properties:
        type:
          type: string
        coordinates:
          type: array
          items:
            $ref: '#/components/schemas/Coordinate'
    Feature:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        geometry:
          $ref: '#/components/schemas/Geometry'
        properties:
          type: object
          additionalProperties:
            type: object
    FeatureCollectionResponse:
      type: object
      properties:
        type:
          type: string
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        timeStamp:
          type: string
          format: date-time
        features:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
    Coordinate:
      type: object
      properties:
        x:
          type: number
          format: double
        y:
          type: number
          format: double
  securitySchemes:
    api-key:
      type: apiKey
      name: key
      in: query
    api-key-header:
      type: apiKey
      name: key
      in: header
    oauth2:
      type: oauth2
      name: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.os.uk/oauth2/token/v1
          scopes: {}