openapi: 3.2.0
info:
  title: OS NGD API - Tiles Tile Sets API
  version: v1.8
servers:
- description: NGD OGC API - Tiles server
  url: https://api.os.uk/maps/vector/ngd/ota/v1
tags:
- name: Tile Sets
paths:
  /collections/{collectionId}/tiles:
    get:
      operationId: .collection.vector.getTileSetsList
      parameters:
      - description: Local identifier of a collection
        in: path
        name: collectionId
        required: true
        schema:
          $ref: '#/components/schemas/AllCollections'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_collection_vector_getTileSetsList_200_response'
          description: List of available tilesets.
        '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 a list of available vector tilesets for the specified collection.
      tags:
      - Tile Sets
  /collections/{collectionId}/tiles/{tileMatrixSetId}:
    get:
      operationId: .collection.vector.getTileSet
      parameters:
      - description: Local identifier of a collection
        in: path
        name: collectionId
        required: true
        schema:
          $ref: '#/components/schemas/AllCollections'
      - allowEmptyValue: false
        description: Identifier for a supported TileMatrixSet
        in: path
        name: tileMatrixSetId
        required: true
        schema:
          $ref: '#/components/schemas/TileSets'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tileSet'
          description: Description of the tileset
        '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 vector tileset metadata for the specified collection and tiling scheme (tile matrix set)
      tags:
      - Tile Sets
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
    propertiesSchema_properties_value:
      description: No property names are defined but any property name they should be described by JSON Schema. So 'additionalProperties' implements 'name'.
      properties:
        type:
          enum:
          - array
          - boolean
          - integer
          - 'null'
          - number
          - object
          - string
          type: string
        enum:
          description: Implements 'acceptedValues'
          items:
            type: object
          minItems: 1
          type: array
          uniqueItems: true
      type: object
    crs:
      description: Reference to one coordinate reference system (CRS)
      format: uri
      title: CRS
      type: string
    tileMatrixLimits:
      description: The limits for an individual tile matrix of a TileSet's TileMatrixSet, as defined in the OGC 2D TileMatrixSet and TileSet Metadata Standard
      properties:
        tileMatrix:
          type: string
        minTileRow:
          minimum: 0
          type: integer
        maxTileRow:
          minimum: 0
          type: integer
        minTileCol:
          minimum: 0
          type: integer
        maxTileCol:
          minimum: 0
          type: integer
      required:
      - maxTileCol
      - maxTileRow
      - minTileCol
      - minTileRow
      - tileMatrix
      title: TileMatrixLimits
      type: object
    propertiesSchema:
      description: Attributes of the features or rangetypes of a coverage. Defined by a subset of the JSON Schema for the properties of a feature
      properties:
        type:
          enum:
          - object
          type: string
        properties:
          additionalProperties:
            $ref: '#/components/schemas/propertiesSchema_properties_value'
          default: {}
          type: object
      required:
      - properties
      - type
      type: object
    TileSets:
      enum:
      - '3857'
      - '27700'
      type: string
    geospatialData:
      properties:
        description:
          description: Brief narrative description of this tile matrix set, normally available for display to a human
          type: string
        id:
          description: Unique identifier of the Layer. Implementation of 'identifier'
          type: string
        dataType:
          allOf:
          - $ref: '#/components/schemas/DataType'
        geometryType:
          type: string
        maxTileMatrix:
          description: TileMatrix identifier associated with the minScaleDenominator
          type: string
        minTileMatrix:
          description: TileMatrix identifier associated with the maxScaleDenominator
          type: string
        propertiesSchema:
          $ref: '#/components/schemas/geospatialData_propertiesSchema'
      required:
      - dataType
      - id
      type: object
    geospatialData_propertiesSchema:
      allOf:
      - description: Properties represented by the features in this layer. Can be the attributes of a feature dataset (datatype=geometries) or the rangeType of a coverage (datatype=coverage)
        type: object
      - $ref: '#/components/schemas/propertiesSchema'
    AllCollections:
      enum:
      - ngd-base
      - asu-bdy
      - wtr-ctch
      - trn-ntwk-railway
      - wtr-tidalboundary
      type: string
    _collection_vector_getTileSetsList_200_response:
      properties:
        links:
          items:
            $ref: '#/components/schemas/link'
          type: array
        tilesets:
          items:
            $ref: '#/components/schemas/tileSet-item'
          type: array
      required:
      - tilesets
      type: object
    DataType:
      description: Type of data
      enum:
      - map
      - vector
      - coverage
      type: string
    tileSet:
      allOf:
      - $ref: '#/components/schemas/tileSet-item'
      - type: object
      description: A resource describing a tileset based on the OGC TileSet Metadata Standard. At least one of the 'TileMatrixSet',  or a link with 'rel' http://www.opengis.net/def/rel/ogc/1.0/tiling-scheme
      properties:
        description:
          description: Brief narrative description of this tile set
          type: string
        tileMatrixSetLimits:
          description: Limits for the TileRow and TileCol values for each TileMatrix in the tileMatrixSet. If missing, there are no limits other that the ones imposed by the TileMatrixSet. If present the TileMatrices listed are limited and the rest not available at all
          items:
            $ref: '#/components/schemas/tileMatrixLimits'
          type: array
        layers:
          items:
            $ref: '#/components/schemas/geospatialData'
          minItems: 1
          type: array
        boundingBox:
          allOf:
          - $ref: '#/components/schemas/BoundingBox2D'
      required:
      - crs
      - dataType
      - links
      title: Tile Set Metadata
      type: object
    tileSet-item:
      description: A minimal tileset element for use within a list of tilesets linking to full description of those tilesets.
      properties:
        id:
          description: identifier of the tile matrix set
          example: '3857'
          type: string
        title:
          description: A title for this tileset
          type: string
        dataType:
          allOf:
          - $ref: '#/components/schemas/DataType'
        crs:
          allOf:
          - $ref: '#/components/schemas/crs'
        tileMatrixSetURI:
          description: 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.
          format: uri
          type: string
        links:
          description: 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.
          items:
            $ref: '#/components/schemas/link'
          type: array
      required:
      - crs
      - dataType
      - links
      title: Tile Set Metadata item
      type: object
    BoundingBox2D:
      description: Minimum bounding rectangle surrounding a 2D resource in the CRS indicated elsewhere
      properties:
        lowerLeft:
          description: A 2D Point in the CRS indicated elsewhere
          items:
            type: number
          maxItems: 2
          minItems: 2
          type: array
        upperRight:
          description: A 2D Point in the CRS indicated elsewhere
          items:
            type: number
          maxItems: 2
          minItems: 2
          type: array
        crs:
          $ref: '#/components/schemas/crs'
      required:
      - lowerLeft
      - upperRight
      type: object
    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
  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: {}