openapi: 3.2.0
info:
  version: 1.0.0
  title: Ordnance Survey Download Open Data API
  description: This api provides access to the OS products that are available to download.
servers:
- url: https://api.os.uk/downloads/v1/
tags:
- name: OpenData
  description: Operations providing access to OpenData products.
paths:
  /products:
    get:
      summary: Returns a list of the OpenData products that are available to download.
      tags:
      - OpenData
      parameters:
      - in: query
        name: expanded
        schema:
          type: boolean
        allowEmptyValue: true
        description: When specified, the full details of each product will be returned.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
  /products/{productId}:
    get:
      summary: Returns details about a specific OpenData product.
      tags:
      - OpenData
      parameters:
      - in: path
        name: productId
        schema:
          type: string
        required: true
        description: The id of the product.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /products/{productId}/downloads:
    get:
      summary: Returns a list of downloads for a specific OpenData product, or redirects to the actual download if requested.
      tags:
      - OpenData
      parameters:
      - in: path
        name: productId
        schema:
          type: string
        required: true
        description: The id of the product.
      - in: query
        name: fileName
        schema:
          type: string
        description: Filter the list of downloads to only include those with this file name.
      - in: query
        name: format
        schema:
          type: string
        description: Filter the list of downloads to only include those with this format.
      - in: query
        name: subformat
        schema:
          type: string
        description: Filter the list of downloads to only include those with this subformat.
      - in: query
        name: area
        schema:
          $ref: '#/components/schemas/Area'
        description: Filter the list of downloads to only include those which cover this area.
      - in: query
        name: redirect
        schema:
          type: boolean
        allowEmptyValue: true
        description: When included, if the selected downloads list contains exactly one download, redirect to the download location.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductDownload'
        '307':
          description: Returned when the 'redirect' parameter was supplied, and there was exactly one matching download.
          headers:
            Location:
              schema:
                type: string
              description: Direct URL for the download file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductDownload'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /products/{productId}/images/{index}:
    get:
      summary: Returns a HTTP redirect, pointing to thumbnail images for the specified OpenData product.
      tags:
      - OpenData
      parameters:
      - in: path
        name: productId
        schema:
          type: string
        required: true
        description: The id of the product.
      - in: path
        name: index
        schema:
          type: integer
        required: true
        description: The index of the image to be retrieved. Valid values are from 0 to (Product.imageCount-1).
      - in: query
        name: large
        schema:
          type: boolean
        allowEmptyValue: true
        description: When set, the image that is returned will be a larger version.
      responses:
        '200':
          description: Successful response.
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        '307':
          description: This response is a redirect to the actual image location.
          headers:
            Location:
              schema:
                type: string
              description: Direct URL for the product image.
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  schemas:
    Area:
      type: string
      description: 'This describes the geographical area that a download covers.

        GB is all of Great Britain, while codes like ''HP'' cover National Grid Reference squares.

        '
      enum:
      - GB
      - HP
      - HT
      - HU
      - HW
      - HX
      - HY
      - HZ
      - NA
      - NB
      - NC
      - ND
      - NF
      - NG
      - NH
      - NJ
      - NK
      - NL
      - NM
      - NN
      - 'NO'
      - NR
      - NS
      - NT
      - NU
      - NW
      - NX
      - NY
      - NZ
      - OV
      - SD
      - SE
      - TA
      - SH
      - SJ
      - SK
      - TF
      - TG
      - SM
      - SN
      - SO
      - SP
      - TL
      - TM
      - SR
      - SS
      - ST
      - SU
      - TQ
      - TR
      - SV
      - SW
      - SX
      - SY
      - SZ
      - TV
    Format:
      type: object
      description: Information about the format that a download is available in.
      required:
      - format
      properties:
        format:
          type: string
          description: File format used for the download.
        subformat:
          type: string
          description: Optional subformat, used when a product is available in more than one style.
    Download:
      type: object
      description: 'Information about a specific download file that is made available through this API.

        '
      required:
      - url
      - fileName
      properties:
        url:
          description: Getting this URL will return a HTTP redirect to the actual data.
          type: string
          format: uri
        fileName:
          description: The name of the file.
          type: string
          example: data.zip
        size:
          description: The file size, in bytes.
          type: integer
          example: 1234
        md5:
          description: A MD5 checksum of the file data. This can be used to verify the integrity of the data once you have downloaded it.
          type: string
          example: 2f9dd13abd56140afa3b5621e8864f59
    ProductDownload:
      description: 'Information about a specific OpenData file that is made available through this API.

        '
      allOf:
      - $ref: '#/components/schemas/Download'
      - type: object
        required:
        - area
        - format
        properties:
          area:
            $ref: '#/components/schemas/Area'
          format:
            description: This describes the format of the data.
            type: string
            example: GML
          subformat:
            description: This describes the subformat of the data.
            type: string
            example: '3'
    ThirdPartyInfo:
      type: object
      description: Information about the data provider for third-party products.
      required:
      - dataProvider
      - supportingInfo
      - alsoAvailable
      - supportEmail
      properties:
        dataProvider:
          type: object
          required:
          - name
          - shortName
          - homepage
          - logoUrl
          properties:
            name:
              type: string
            shortName:
              type: string
            homepage:
              type: string
            logoUrl:
              type: string
              format: uri
        supportingInfo:
          type: array
          minItems: 0
          items:
            type: object
            required:
            - name
            - link
            properties:
              name:
                type: string
              link:
                type: string
                format: uri
        alsoAvailable:
          type: array
          minItems: 0
          items:
            type: object
            required:
            - name
            - link
            properties:
              name:
                type: string
              link:
                type: string
                format: uri
        supportEmail:
          type: string
          format: email
    Product:
      type: object
      description: Information about a product made available through this API.
      required:
      - id
      - name
      - description
      - version
      - url
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: array
          minItems: 1
          items:
            type: string
        version:
          type: string
          pattern: ^/d{4}-/d{2}$
        thirdPartyInfo:
          $ref: '#/components/schemas/ThirdPartyInfo'
        url:
          type: string
        documentationUrl:
          type: string
        areas:
          type: array
          items:
            $ref: '#/components/schemas/Area'
        dataStructures:
          type: array
          items:
            type: string
            enum:
            - Raster
            - Vector
        category:
          type: string
        categories:
          type: array
          items:
            type: string
        formats:
          type: array
          items:
            $ref: '#/components/schemas/Format'
        imageCount:
          type: integer
        imageTemplate:
          type: string
        downloadsUrl:
          type: string
          format: uri
        warning:
          type: string
        endOfLife:
          type: string
          pattern: ^/d{4}-/d{2}-/d{2}$
  responses:
    NotFoundError:
      description: 'The request does not match any known content.

        The response will contain a human readable message, and may also contain links to help you

        navigate to other API endpoints.

        '
      content:
        application/json:
          schema:
            type: object
            required:
            - message
            properties:
              message:
                type: string
              dataPackagesUrl:
                type: string
                format: uri
              downloadCatalogueUrl:
                type: string
                format: uri
              productUrl:
                type: string
                format: uri
              productDownloadsUrl:
                type: string
                format: uri
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.os.uk/oauth2/token/v1
          scopes: {}
    APIKeyQuery:
      type: apiKey
      in: query
      name: key
    APIKeyHeader:
      type: apiKey
      in: header
      name: key