openapi: 3.0.0
info:
  title: GOV.UK Content Data API
  description: |
    GOV.UK Content Data API provides metrics about GOV.UK content.

    This API accepts HTTP requests and responds with
    [JSON](https://en.wikipedia.org/wiki/JSON).
  version: 1.0.0
servers:
  - url: 'https://content-data-api.publishing.service.gov.uk/api/v1'
    description: Production
  - url: 'https://content-data-api.staging.publishing.service.gov.uk/api/v1'
    description: Staging
  - url: 'https://content-data-api.integration.publishing.service.gov.uk/api/v1'
    description: Integration
  - url: 'http://content-data-api.dev.gov.uk/api/v1'
    description: Development
paths:
  '/organisations/':
    get:
      summary: Get all organisations
      responses:
        '200':
           description: A list of organisations
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ArrayOfOrganisations'
  '/document_types/':
    get:
      summary: Get all document types
      responses:
        '200':
           description: A list of document types
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ArrayOfDocumentTypes'
  '/metrics/':
    get:
      summary: List all available metrics.
      description: |
        Returns a list of available metrics for content items.
      tags:
        - Metadata
      responses:
        '200':
          description: |
            Success response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Metric'
              example:
                $ref: '#/components/examples/MetricsExample'
      x-code-samples:
        /metrics/:
          lang: shell
          source: >-
            curl
            'https://content-data-api.publishing.service.gov.uk/api/v1/metrics/'
  '/metrics/{base_path}':
    get:
      summary: Get summarised metrics for a content item.
      description: >
        Returns a summary of a metric based on data collected over a time
        period.
      tags:
        - Aggregations
      parameters:
        - name: base_path
          in: path
          required: true
          description: >
            A GOV.UK base path. A reserved URL on www.gov.uk that is associated
            with a content item.
          schema:
            type: string
            example: /vat-rates
        - name: metrics
          in: path
          required: true
          description: |
            The names of metrics.
          schema:
            type: string
            example: pviews
        - name: from
          in: query
          required: true
          description: >
            From date in the format 'YYYY-MM-DD'. Only data collected on or
            after this date will be included.
          schema:
            type: string
            example: '2018-01-01'
        - name: to
          in: query
          required: true
          description: >
            To date in the format 'YYYY-MM-DD'. Only data collected on or before
            this date will be included.
          schema:
            type: string
            example: '2018-01-01'
      responses:
        '200':
          description: |
            Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryResponse'
        '400':
          description: The API request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-code-samples:
        /metrics/f838c22a-b2aa-49be-bd95-153f593293a3:
          lang: shell
          source: >-
            curl
            'https://content-data-api.publishing.service.gov.uk/api/v1/metrics/vat-rates?from=2018-02-27&to=2018-02-27&metrics[]=upviews&metrics[]=pviews'
  '/metrics/{base_path}/time-series':
    get:
      summary: Get metric values for a single content item over a date range.
      description: |
        Returns an array of values for each metric. Each item represents a
        metric value at a single point in time.
      tags:
        - Time series
      parameters:
        - name: base_path
          in: path
          required: true
          description: >
            A GOV.UK base path. A reserved URL on www.gov.uk that is associated
            with a content item.
          schema:
            type: string
            example: /vat-rates
        - name: metrics
          in: path
          required: true
          description: |
            The names of metrics.
          schema:
            type: string
            example: pviews
        - name: from
          in: query
          required: true
          description: >
            From date in the format 'YYYY-MM-DD'. Only data collected on or
            after this date will be returned.
          schema:
            type: string
            example: '2018-01-01'
        - name: to
          in: query
          required: true
          description: >
            To date in the format 'YYYY-MM-DD'. Only data collected on or before
            this date will be returned.
          schema:
            type: string
            example: '2018-01-01'
      responses:
        '200':
          description: |
            Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeSeriesResponse'
        '400':
          description: The API request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                $ref: '#/components/examples/ErrorExample'
      x-code-samples:
        /metrics/vat-rates:
          lang: shell
          source: >-
            curl
            'https://content-data-api.publishing.service.gov.uk/api/v1/metrics/vat-rates/time-series?from=2018-02-27&to=2018-02-27&metrics[]=upviews&metrics[]=pviews'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Organisation:
      requires:
        - id
        - name
      properties:
        id:
          type: string 
        name:
          type: string
    ArrayOfOrganisations:
      type: array
      items:
        $ref: '#/components/schemas/Organisation'
    DocumentType:
      requires:
        - id
        - name
      properties:
        id:
          type: string 
        name:
          type: string
    ArrayOfDocumentTypes:
      type: array
      items:
        $ref: '#/components/schemas/DocumentType'
    Metric:
      description: |
        Information about a metric returned by the API.
      type: object
      required:
        - metric_id
        - description
      properties:
        metric_id:
          type: string
          description: ID to refer to the metric within the API
        description:
          type: string
          description: Description of the metric
        source:
          type: string
          description: Where this metric comes from
    Summary:
      description: |
        Summarised metric data for a defined time period
      type: object
      required:
        - total
        - latest
      properties:
        total:
          type: integer
          description: Sum of all recorded metric values within the date range.
        latest:
          type: integer
          description: The latest recorded metric value within the date range.
    Value:
      description: |
        A single observation of a metric.
      type: object
      required:
        - date
        - value
      properties:
        date:
          type: string
          description: Date of measurement, in the form YYYY-MM-DD.
        value:
          type: integer
          description: The value of the metric.
    TimeSeries:
      description: |
        A series of values for a metric.
      type: array
      items:
        $ref: '#/components/schemas/Value'
    TimeSeriesResponse:
      description: An object where each key is a metric ID and each value is a time series.
      type: object
      additionalProperties:
        $ref: '#/components/schemas/TimeSeries'
    SummaryResponse:
      description: Summary information keyed by metric ID.
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Summary'
    ErrorResponse:
      description: An error response.
      type: object
      required:
        - title
        - type
      properties:
        title:
          type: string
          description: A human readable summary of the error.
        invalid_params:
          type: object
          description: An array of error messages for each invalid parameter.
        type:
          type: string
          description: A URI identifying the error.
      example:
        $ref: '#/components/examples/ErrorExample'
  examples:
    ErrorExample:
      summary: An example of an error.
      value:
        title: One or more parameters is invalid
        invalid_params:
          from:
            - can't be blank
            - Dates should use the format YYYY-MM-DD
          to:
            - can't be blank
            - Dates should use the format YYYY-MM-DD
        type: >-
          https://content-data-api.publishing.service.gov.uk/errors.html#validation-error
    MetricsExample:
      summary: An list of available metrics.
      value:
        - description: Number of pageviews
          source: Google Analytics
          metric_id: pviews
        - description: Number of unique pageviews
          source: Google Analytics
          metric_id: upviews
        - description: Number of reported content issues
          source: Feedback explorer
          metric_id: feedex
        - description: Number of .pdf attachments
          source: Publishing API
          metric_id: pdf_count
security:
  - bearerAuth: []