swagger.yaml

swagger: "2.0"
info:
  description: "The Search and Release API lets you search and retrieve various releases. Use this API to query datasets, articles, and publications by search terms, content types, and filters like topics, population types, and dimensions. It supports pagination, sorting, and highlighting of search results. Additionally, it includes endpoints for checking the health status of the API and creating new Elasticsearch indexes."
  version: "1.0.0"
  title: "Search API"
  license:
    name: "Open Government Licence v3.0"
    url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
basePath: "/v1"
schemes:
  - "http"
tags:
  - name: "public"
  - name: "private"
paths:
  /health:
    get:
      tags:
        - public
      summary: "Health check API"
      description: "API to query the app for current health status"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Health"
        500:
          description: Internal Server Error

  /search:
    get:
      tags:
        - public
      summary: "Default ONS query API"
      description: "Default ONS query API which combines the content with type counts"
      parameters:
        - in: query
          name: q
          description: "Query search term."
          type: string
          required: true
        - in: query
          name: content_type
          description: "Comma-separated list of content types to be returned."
          type: array
          items:
            type: string
          collectionFormat: csv
          required: false
        - in: query
          name: topics
          description: "Comma-separated list of topics to be returned."
          type: array
          items:
            type: string
          collectionFormat: csv
          required: false
        - in: query
          name: population_types
          description: "Comma-separated list of population type names to filter the results (or)."
          type: array
          items:
            type: string
          collectionFormat: csv
          required: false
        - in: query
          name: dimensions
          description: "Comma-separated list of dimension names to filter the results (and)."
          type: array
          items:
            type: string
          collectionFormat: csv
          required: false
        - in: query
          name: cdids
          description: "Comma-separated list of cdids to filter the results (or)."
          type: array
          items:
            type: string
          collectionFormat: csv
          required: false
        - in: query
          name: dataset_ids
          description: "Comma-separated list of dataset IDs to filter the results."
          type: array
          items:
            type: string
          collectionFormat: csv
          required: false
        - in: query
          name: highlight
          description: "Determines whether to return HTML highlighted fields."
          type: boolean
          required: false
          default: true
        - in: query
          name: sort
          description: "The order to return the results."
          type: string
          required: false
        - in: query
          name: limit
          description: "The number of items requested, defaulted to 10 and limited to 1000."
          type: integer
          required: false
          default: 10
        - in: query
          name: offset
          description: "The first row of resources to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter."
          type: integer
          required: false
          default: 0
        - in: query
          name: fromDate
          description: "Specifies candidate results by their ReleaseDate, which must be on or after the fromDate"
          type: string
          required: false
        - in: query
          name: toDate
          description: "Specifies candidate results by their ReleaseDate, which must be on or before the toDate"
          type: string
          required: false
        - in: query
          name: nlp_weighting
          description: "Runs query through NLP processors to influence search weighting"
          type: boolean
          required: false
        - name: uri_prefix
          in: query
          description: URI prefix to filter the search results e.g. `/economy`
          required: false
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/GetSearchResponse"
        400:
          description: Query term not specified
        500:
          description: Internal server error
    post:
      tags:
        - private
      summary: "Create new empty ONS Elasticsearch index"
      description: "Request a new search index and receive the name of the new index created in response. Endpoint requires service or user authentication."
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/PostSearchResponse"
        500:
          description: Internal server error

  /search/releases:
    get:
      tags:
        - public
      summary: "ONS query API for published or upcoming releases"
      description: "ONS query API specifically targeting already Published (or Cancelled) Releases, or upcoming Release Calendar Entries"
      parameters:
        - in: query
          name: limit
          description: "The number of Resources requested, defaulted to 10 and limited to 1000."
          type: integer
          required: false
          default: 10
        - in: query
          name: offset
          description: "The offset into the complete ordered set of Resources which satisfy the query, which specifies the first Resource to return (starting at 0). Use this parameter as a pagination mechanism along with the limit parameter."
          type: integer
          required: false
          default: 0
        - in: query
          name: sort
          description: "The sort order of the returned set of Releases"
          type: string
          required: false
          default: "release_date_asc"
          enum: ["release_date_asc", "release_date_desc", "title_asc", "title_desc", "relevance"]
        - in: query
          name: query
          description: "Query keywords"
          type: string
          required: false
        - in: query
          name: fromDate
          description: "Specifies candidate Releases by their ReleaseDate, which must be on or after the fromDate"
          type: string
          required: false
        - in: query
          name: toDate
          description: "Specifies candidate Releases by their ReleaseDate, which must be on or before the toDate"
          type: string
          required: false
        - in: query
          name: release-type
          description: "The type of releases to include in the results."
          type: string
          required: false
          default: type-published
          enum: ["type-upcoming", "type-published", "type-cancelled"]
        - in: query
          name: highlight
          description: "Determines whether to return HTML highlighted fields."
          type: boolean
          required: false
          default: true
        - in: query
          name: census
          description: "Whether to only include census releases in the results."
          type: boolean
          required: false
          default: false
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/SearchReleaseResponse"
        500:
          description: Internal server error

  /search/uris:
    post:
      tags:
        - public
      summary: "Search URIs by list"
      description: "Accepts a list of URIs and returns matching results based on provided criteria."
      parameters:
        - in: body
          name: body
          description: "Request object containing URIs and optional pagination parameters."
          required: true
          schema:
            type: object
            properties:
              uris:
                type: array
                items:
                  type: string
                description: "List of URIs to filter the search results."
                example: [ "/economy", "/health" ]
              limit:
                type: integer
                description: "The number of items requested, defaulted to 10 and limited to 100."
                example: 10
              offset:
                type: integer
                description: "The first row of resources to retrieve, starting at 0."
                example: 0
              sort:
                type: string
                description: "The sort order of the returned set of results."
                enum: [ "relevance", "release_date", "title"]
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              count:
                type: integer
                description: "The number of matching URIs."
                example: 5
              results:
                type: array
                items:
                  type: string
                description: "List of matching URIs."
                example: [ "/economy/data", "/economy/reports" ]
        400:
          description: "Bad Request - Invalid request format or parameters"
        500:
          description: "Internal server error"


definitions:
  Health:
    type: object
    properties:
      status:
        type: string
        description: "The status of the API"
        enum: ["OK", "WARNING", "CRITICAL"]
      version:
        type: object
        properties:
          build_time:
            type: string
            description: "The build date and time of the API"
            example: "2020-06-11T12:49:20+01:00"
          git_commit:
            type: string
            description: "The git commit hash of the API"
            example: "7c2febbf2b818175112478d4ffbadbee1b654f63"
          language:
            type: string
            description: "The programming language used to implement API"
            example: "go"
          language_version:
            type: string
            description: "The version of the programming language used to implement API"
            example: "go1.14.3"
          version:
            type: string
            description: "The version of API"
            example: "1.0.0"
      uptime:
        type: string
        description: "The uptime of API"
        example: "34516"
      start_time:
        type: string
        description: "The start date and time of API running"
        example: "2020-06-11T11:49:21.520922Z"
      checks:
        type: array
        items:
          $ref: '#/definitions/HealthChecker'

  HealthChecker:
    type: object
    properties:
      name:
        type: string
        description: "The name of external service used by API"
        enum: ["mongodb"]
      status:
        type: string
        description: "The status of the external service"
        enum: ["OK", "WARNING", "CRITICAL"]
      message:
        type: string
        description: "The message status of the external service"
        example: "mongodb is OK"
      last_checked:
        type: string
        description: "The last health check date and time of the external service"
        example: "2020-06-11T11:49:50.330089Z"
      last_success:
        type: string
        description: "The last successful health check date and time of the external service"
        example: "2020-06-11T11:49:50.330089Z"
      last_failure:
        type: string
        description: "The last failed health check date and time of the external service"
        example: "2019-09-22T11:48:51.0000001Z"

  GetSearchResponse:
    type: object
    properties:
      count:
        type: number
        description: "Number of search results which match query"
        example: 80
      took:
        type: number
        description: "Time taken to execute query in milliseconds"
        example: 530
      distinct_items_count:
        type: integer
        description: "Count of distinct items that match the query"
        example: 100
      dimensions:
        type: array
        description: "List of dimensions included in results"
        items:
          $ref: "#/definitions/CountItem"
      content_types:
        type: array
        description: "List of content types included in results"
        items:
          $ref: "#/definitions/CountItem"
      population_type:
        type: array
        description: "List of population types included in results"
        items:
          $ref: "#/definitions/CountItem"
      topics:
        type: array
        description: "List of topics included in results"
        items:
          $ref: "#/definitions/CountItem"
      items:
        type: array
        description: "List of matching content items for the current page"
        items:
          $ref: "#/definitions/ContentItem"
      suggestions:
        type: array
        description: "List of suggested alternative similar search queries"
        items:
          type: string
      additional_suggestions:
        type: array
        description: "List of suggested alternative search queries from current search query"
        items:
          type: string
        example: ['UK', 'economy', "inflation rate"]
    required:
      - count
      - took
      - distinct_items_count
      - content_types
      - items

  PostSearchResponse:
    type: object
    properties:
      index_name:
        type: string
        description: "Name of new empty search index"
        example: "ons1636458168532"
    required:
      - index_name

  SearchReleaseResponse:
    type: object
    properties:
      took:
        type: number
        description: "Time taken to execute query in milliseconds"
        example: 530
      breakdown:
        description: "Breakdown of the total number of Releases into defined categories"
        $ref: "#/definitions/Breakdown"
      releases:
          type: array
          description: "List of matching Releases"
          items:
            $ref: "#/definitions/Release"
    required:
      - took
      - breakdown
      - releases

  Breakdown:
    type: object
    properties:
      total:
        type: number
        description: "Total number of Releases which match query"
        example: 80
      provisional:
        type: number
        description: "Number of provisional Releases"
        example: 5
      confirmed:
        type: number
        description: "Number of confirmed Releases"
        example: 5
      published:
        type: number
        description: "Number of published Releases"
        example: 5
      cancelled:
        type: number
        description: "Number of cancelled Releases"
        example: 5
      census:
        type: number
        description: "Number of Releases that are related to Census"
        example: 5
    required:
      - total

  Dimension: 
    type: object
    properties:
      label:
        type: string
      raw_label:
        type: string
      name:
        type: string

  ContentItem:
    type: object
    properties:
      description:
        type: object
        properties:
          contact:
            type: object
            properties:
              email:
                type: string
              name:
                type: string
              telephone:
                type: string
            required:
              - name
              - email
          dataset_id:
            type: string
          dimensions:
            type: array
            items:
              $ref: "#/definitions/Dimension"
            description: "An array of dimensions within a dataset."
          edition:
            type: string
          highlight:
            $ref: "#/definitions/Highlight"
          headline1:
            type: string
          headline2:
            type: string
          headline3:
            type: string
          keywords:
            type: array
            items:
              type: string
          latest_release:
            type: boolean
          language:
            type: string
            example: "English"
          meta_description:
            type: string
          national_statistic:
            type: boolean
          next_release:
            type: string
            example: "14 August 2015"
          population_type:
            type: string
            description: "A population type a dataset is associated with e.g. Usual-Residents.  This is applicable to Census 2021 datasets only."
          pre_unit:
            type: string
          release_date:
            type: string
            format: date-time
          source:
            type: string
          summary:
            type: string
          title:
            type: string
          topics:
            type: array
            items:
              type: string
          unit:
            type: string
        required:
          - summary
          - title
      type:
        type: string
      uri:
        type: string
    required:
      - description
      - type
      - uri

  CountItem:
    type: object
    properties:
      type:
        type: string
      count:
        type: integer
    required:
      - type
      - count

  Release:
    type: object
    properties:
      uri:
        type: string
      date_changes:
        type: array
        items:
          type: object
          properties:
            previous_date:
              type: string
            change_notice:
              type: string
      description:
        type: object
        properties:
          title:
            type: string
          summary:
            type: string
          release_date:
            type: string
            format: date-time
          published:
            type: boolean
          cancelled:
            type: boolean
          finalised:
            type: boolean
          postponed:
            type: boolean
          census:
            type: boolean
          keywords:
            type: array
            items:
              type: string
          provisional_date:
            type: string
            format: date-time
          language:
            type: string
        required:
          - title
          - summary
          - release_date
          - published
          - cancelled
          - finalised
          - postponed
          - census
      highlight:
        $ref: "#/definitions/Highlight"
    required:
      - uri
      - description

  Highlight:
    description: "Fields that contain at least 1 matching term from query 'q' parameter. The values contain the following embedded tags \"...<em class=\"highlight\">{matched term}</em>...\""
    type: object
    properties:
      summary:
        type: string
      title:
        type: string
      keywords:
        type: array
        items:
          type: string