openapi: 3.2.0
info:
  title: OS NGD API - Tiles Data Collections API
  version: v1.8
servers:
- description: NGD OGC API - Tiles server
  url: https://api.os.uk/maps/vector/ngd/ota/v1
tags:
- name: Data Collections
paths:
  /collections:
    get:
      operationId: getCollectionsList
      responses:
        '200':
          content:
            application/json:
              example:
                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.
                  extent:
                    spatial:
                      bbox:
                      - - -8.82
                        - 49.79
                        - 1.92
                        - 60.94
                    temporal:
                      interval:
                      - - '2022-08-27T00:00:00Z'
                        - null
                  links:
                  - href: http://data.example.org/collections/buildingpart/items
                    rel: items
                    type: application/geo+json
                    title: Building Part
              schema:
                $ref: '#/components/schemas/collections'
            text/html:
              schema:
                type: string
          description: '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'').'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: The request was not supported.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: The requested resource does not exist on the server. For example, a path parameter had an incorrect value.
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: The HTTP method requested is not supported. This endpoint only supports 'GET' requests.
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: A request header value was not supported.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: A server error occurred.
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: Gateway Timeout.
      summary: Retrieve the list of geospatial data collections available from this service.
      tags:
      - Data Collections
  /collections/{collectionId}:
    get:
      operationId: getCollection
      parameters:
      - description: Local identifier of a collection
        in: path
        name: collectionId
        required: true
        schema:
          $ref: '#/components/schemas/AllCollections'
      responses:
        '200':
          content:
            application/json:
              example:
                id: buildingpart
                title: Building Part
                description: Polygon feature representing a building.
                extent:
                  spatial:
                    bbox:
                    - - -8.82
                      - 49.79
                      - 1.92
                      - 60.94
                  temporal:
                    interval:
                    - - '2022-08-27T00:00:00Z'
                      - null
                links:
                - href: http://data.example.org/collections/buildingpart/items
                  rel: items
                  type: application/geo+json
                  title: Building Part
              schema:
                $ref: '#/components/schemas/collectionInfo'
          description: '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'').'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: The request was not supported.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: The requested resource does not exist on the server. For example, a path parameter had an incorrect value.
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: The HTTP method requested is not supported. This endpoint only supports 'GET' requests.
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: A request header value was not supported.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: A server error occurred.
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exceptionDto'
          description: Gateway Timeout.
      summary: Retrieve the description of a collection available from this service.
      tags:
      - Data Collections
components:
  schemas:
    exceptionDto:
      description: JSON schema for exceptions based on RFC 7807
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        code:
          type: integer
        description:
          type: string
        help:
          type: string
      required:
      - type
      title: Exception Schema
      type: object
    extent-uad:
      allOf:
      - $ref: '#/components/schemas/extent'
      - type: object
      description: '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.'
      title: Extent with Uniform Additional Dimensions Schema
    extent:
      description: 'The extent of the data in the collection. In the Core only spatial and temporal

        extents are specified. Extensions may add additional members to represent other

        extents, for example, thermal or pressure ranges.


        The first item in the array describes the overall extent of

        the data. All subsequent items describe more precise extents,

        e.g., to identify clusters of data.

        Clients only interested in the overall extent will only need to

        access the first item in each array.'
      properties:
        spatial:
          $ref: '#/components/schemas/extent_spatial'
      type: object
    collections:
      properties:
        links:
          items:
            $ref: '#/components/schemas/link'
          type: array
        collections:
          items:
            $ref: '#/components/schemas/collectionInfo'
          type: array
      required:
      - collections
      - links
      type: object
    extent_spatial:
      description: The spatial extent of the data in the collection.
      properties:
        bbox:
          description: 'One or more bounding boxes that describe the spatial extent of the dataset.

            In the Core only a single bounding box is supported.


            Extensions may support additional areas.

            The first bounding box describes the overall spatial

            extent of the data. All subsequent bounding boxes describe

            more precise bounding boxes, e.g., to identify clusters of data.

            Clients only interested in the overall spatial extent will

            only need to access the first item in each array.'
          items:
            description: 'Each bounding box is provided as four or six numbers, depending on

              whether the coordinate reference system includes a vertical axis

              (height or depth):


              * Lower left corner, coordinate axis 1

              * Lower left corner, coordinate axis 2

              * Minimum value, coordinate axis 3 (optional)

              * Upper right corner, coordinate axis 1

              * Upper right corner, coordinate axis 2

              * Maximum value, coordinate axis 3 (optional)


              If the value consists of four numbers, the coordinate reference system is

              WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84)

              unless a different coordinate reference system is specified in a parameter `bbox-crs`.


              If the value consists of six numbers, the coordinate reference system is WGS 84

              longitude/latitude/ellipsoidal height (http://www.opengis.net/def/crs/OGC/0/CRS84h)

              unless a different coordinate reference system is specified in a parameter `bbox-crs`.


              For WGS 84 longitude/latitude the values are in most cases the sequence of

              minimum longitude, minimum latitude, maximum longitude and maximum latitude.

              However, in cases where the box spans the antimeridian the first value

              (west-most box edge) is larger than the third value (east-most box edge).


              If the vertical axis is included, the third and the sixth number are

              the bottom and the top of the 3-dimensional bounding box.


              If a feature has multiple spatial geometry properties, it is the decision of the

              server whether only a single spatial geometry property is used to determine

              the extent or all relevant geometries.'
            example:
            - -180
            - -90
            - 180
            - 90
            items:
              type: number
            maxItems: 4
            minItems: 4
            type: array
          minItems: 1
          type: array
        crs:
          default: http://www.opengis.net/def/crs/EPSG/0/3857
          description: 'Coordinate reference system of the coordinates in the spatial extent

            (property `bbox`). The default reference system is WGS 84 longitude/latitude.

            In the Core the only other supported coordinate reference system is

            WGS 84 longitude/latitude/ellipsoidal height for coordinates with height.

            Extensions may support additional coordinate reference systems and add

            additional enum values.'
          enum:
          - http://www.opengis.net/def/crs/EPSG/0/3857
          - http://www.opengis.net/def/crs/EPSG/0/3857h
          - http://www.opengis.net/def/crs/OGC/1.3/CRS84
          - http://www.opengis.net/def/crs/OGC/0/CRS84h
          type: string
      type: object
    AllCollections:
      enum:
      - ngd-base
      - asu-bdy
      - wtr-ctch
      - trn-ntwk-railway
      - wtr-tidalboundary
      type: string
    link:
      properties:
        href:
          description: Supplies the URI to a remote resource (or resource fragment).
          example: http://data.example.com/buildingpart/123
          type: string
        rel:
          description: The type or semantics of the relation.
          example: alternate
          type: string
        type:
          description: A hint indicating what the media type of the result of dereferencing the link should be.
          example: application/geo+json
          type: string
        templated:
          description: This flag set to true if the link is a URL template.
          type: boolean
        varBase:
          description: A base path to retrieve semantic information about the variables used in URL template.
          example: /ogcapi/vars/
          type: string
        hreflang:
          description: A hint indicating what the language of the result of dereferencing the link should be.
          example: en
          type: string
        title:
          description: Used to label the destination of a link such that it can be used as a human-readable identifier.
          example: Building Part
          type: string
        length:
          type: integer
      required:
      - href
      - rel
      type: object
    collectionInfo:
      properties:
        id:
          description: identifier of the collection used, for example, in URIs
          example: buildingpart
          type: string
        title:
          description: human readable title of the collection
          example: Building Part
          type: string
        description:
          description: a description of the data in the collection
          example: Polygon feature representing a building.
          type: string
        links:
          example:
          - href: http://data.example.org/collections/buildingpart
            rel: self
            type: application/json
            title: Building Part
          items:
            $ref: '#/components/schemas/link'
          type: array
        extent:
          $ref: '#/components/schemas/extent-uad'
      required:
      - id
      - links
      type: object
  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: {}