swagger: '2.0'
info:
  title: Planning Dashboard Stats API
  description: |-
    Dashboard stats endpoints for planning.

    Available endpoints (examples):
    - GET /api/planning/dashboard-stats/planned-vs-achieved-kms/?financial_year=2025-26&authority_code=KeNHA&authority_code=KeRRA
    - GET /api/planning/dashboard-stats/road-condition-mix/?financial_year=2025-26&authority_code=KeNHA
    - GET /api/planning/dashboard-stats/planned-km-and-avg-cost/?financial_year=2025-26

    All endpoints accept the common filter params (authority_code, financial_year, funding_source, fund_type)
    and extra filters (region_or_county, city_or_municipality, constituency, national_park_or_game_reserve, surface_type, work_category, etc.).
    If header_ids/header_id is provided, it takes precedence and the 4-key filters are ignored.
  contact:
    email: eomoro@krb.go.ke
  license:
    name: BSD License
  version: v1
host: aprpms.devsgraphics.com
schemes:
- http
basePath: /api/planning/dashboard-stats
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  Basic:
    type: basic
security:
- Basic: []
paths:
  /planned-km-and-avg-cost/:
    get:
      operationId: planned-km-and-avg-cost_list
      summary: Planned KM + Avg Cost (cards + series + rows)
      description: GET /api/planning/dashboard-stats/planned-km-and-avg-cost/
      parameters:
      - name: header_ids
        in: query
        description: Filter by one or more WorkplanHeader UUIDs. If provided, header_ids
          takes precedence and the 4-key filters are ignored.
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: header_id
        in: query
        description: Alias of header_ids (repeatable). If provided, takes precedence
          and 4-key filters are ignored.
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: authority_code
        in: query
        description: Filter by one or more authority codes
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: financial_year
        in: query
        description: Filter by one or more financial years (e.g., 2024-25)
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: funding_source
        in: query
        description: Filter by one or more funding sources
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: fund_type
        in: query
        description: Filter by one or more fund types
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: region_or_county
        in: query
        description: Filter by one or more Region/County values
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: city_or_municipality
        in: query
        description: Filter by one or more Cities/Municipalities
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: work_category
        in: query
        description: Filter by one or more Work Categories
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: surface_type
        in: query
        description: Filter by one or more Surface Types
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: road_condition_status
        in: query
        description: Filter by one or more Road Condition Status values
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: constituency
        in: query
        description: Filter by one or more Constituencies
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: national_park_or_game_reserve
        in: query
        description: Filter by one or more Parks/Reserves
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: vat_rate_pct
        in: query
        description: Override VAT percent for scenario testing (e.g., 16 or 16.00).
        required: false
        type: string
      responses:
        '200':
          description: Dashboard payload
      tags:
      - planned-km-and-avg-cost
    parameters: []
  /planned-vs-achieved-kms/:
    get:
      operationId: planned-vs-achieved-kms_list
      summary: Planned vs Achieved KMs (cards + series + rows)
      description: ''
      parameters:
      - name: header_ids
        in: query
        description: Filter by one or more WorkplanHeader UUIDs. If provided, header_ids
          takes precedence and the 4-key filters are ignored.
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: header_id
        in: query
        description: Alias of header_ids (repeatable). If provided, takes precedence
          and 4-key filters are ignored.
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: authority_code
        in: query
        description: Filter by one or more authority codes
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: financial_year
        in: query
        description: Filter by one or more financial years (e.g., 2024-25)
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: funding_source
        in: query
        description: Filter by one or more funding sources
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: fund_type
        in: query
        description: Filter by one or more fund types
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: region_or_county
        in: query
        description: Filter by one or more Region/County values
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: city_or_municipality
        in: query
        description: Filter by one or more Cities/Municipalities
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: work_category
        in: query
        description: Filter by one or more Work Categories
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: surface_type
        in: query
        description: Filter by one or more Surface Types
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: road_condition_status
        in: query
        description: Filter by one or more Road Condition Status values
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: constituency
        in: query
        description: Filter by one or more Constituencies
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: national_park_or_game_reserve
        in: query
        description: Filter by one or more Parks/Reserves
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: vat_rate_pct
        in: query
        description: Override VAT percent for scenario testing (e.g., 16 or 16.00).
        required: false
        type: string
      responses:
        '200':
          description: Dashboard payload
      tags:
      - planned-vs-achieved-kms
    parameters: []
  /road-condition-mix/:
    get:
      operationId: road-condition-mix_list
      summary: Road Condition Mix per Agency
      description: GET /api/planning/dashboard-stats/road-condition-mix/
      parameters:
      - name: header_ids
        in: query
        description: Filter by one or more WorkplanHeader UUIDs. If provided, header_ids
          takes precedence and the 4-key filters are ignored.
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: header_id
        in: query
        description: Alias of header_ids (repeatable). If provided, takes precedence
          and 4-key filters are ignored.
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: authority_code
        in: query
        description: Filter by one or more authority codes
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: financial_year
        in: query
        description: Filter by one or more financial years (e.g., 2024-25)
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: funding_source
        in: query
        description: Filter by one or more funding sources
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: fund_type
        in: query
        description: Filter by one or more fund types
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: region_or_county
        in: query
        description: Filter by one or more Region/County values
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: city_or_municipality
        in: query
        description: Filter by one or more Cities/Municipalities
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: work_category
        in: query
        description: Filter by one or more Work Categories
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: surface_type
        in: query
        description: Filter by one or more Surface Types
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: road_condition_status
        in: query
        description: Filter by one or more Road Condition Status values
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: constituency
        in: query
        description: Filter by one or more Constituencies
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: national_park_or_game_reserve
        in: query
        description: Filter by one or more Parks/Reserves
        type: array
        items:
          type: string
        collectionFormat: multi
      - name: vat_rate_pct
        in: query
        description: Override VAT percent for scenario testing (e.g., 16 or 16.00).
        required: false
        type: string
      responses:
        '200':
          description: Road condition mix payload
      tags:
      - road-condition-mix
    parameters: []
definitions: {}
