#
# This file is hand-written; you can edit it!
#
# TODO(ryan): generate this from proto.
openapi: 3.1.0
info:
  title: Wattch Kiosk API
  description: Provides public sharable data about sites. Meant to be displayed e.g. on a TV in a lobby or an elevator.
  version: 2.0.0
servers:
  - url: https://kiosk.wattch.io/api/v2
    description: Production
  - url: https://kiosk.staging.wattch.io/api/v2
    description: Staging
  - url: http://{ipAddress}:4203/api/v2
    description: Local
    variables:
      ipAddress:
        default: 127.0.0.1
        description: IP address of the server (copy/paste address used to access this page)
components:
  parameters:
    SiteID:
      name: SiteID
      in: path
      required: true
      description: The ID of the requested site
      schema:
        type: string
    PortfolioID:
      name: PortfolioID
      in: path
      required: true
      description: The ID of the requested portfolio
      schema:
        type: string
  schemas:
    SiteWorkflowStatus:
      type: string
      description: The status of the site in the organizational pipeline.
      enum:
        - PIPELINE
        - BACKLOG
        - DESIGN
        - CONSTRUCTION
        - BUILT
        - ENERGIZED
        - DECOMMISSIONED
    DateValue:
      properties:
        date:
          type: string
          format: date
        value:
          type: number
          format: double
          example: 3.2
      required:
        - date
    Location:
      properties:
        address1:
          type: string
          example: 691 John Wesley Dobbs Ave NE
        address2:
          type: string
          example: Unit H
        city:
          type: string
          example: Atlanta
        state:
          type: string
          example: GA
        country:
          type: string
          example: USA
        zip:
          type: string
          example: 30312
        latitude:
          type: number
          format: double
          minimum: -90
          maximum: 90
          example: 33.759186
        longitude:
          type: number
          format: double
          minimum: -180
          maximum: 180
          example: -84.364208
        timezone:
          description: Time zone in the IANA time zone database format.
          type: string
          example: America/New_York
      required:
        - timezone
    WeatherIcon:
      type: string
      enum:
        - CLEAR_DAY
        - CLEAR_NIGHT
        - RAIN
        - SNOW
        - SLEET
        - WIND
        - FOG
        - CLOUDY
        - PARTLY_CLOUDY_DAY
        - PARTLY_CLOUDY_NIGHT
    MeteoData:
      description: Meteorological data for the site. Temperature is in degrees Celsius.
      properties:
        temperature:
          type: number
          format: double
        cloudCover:
          type: number
          format: double
          minimum: 0
          maximum: 1
        icon:
          $ref: "#/components/schemas/WeatherIcon"
    LiveValue:
      properties:
        lastUpdated:
          description: The time at which this value was last updated.
          type: string
          format: date-time
        value:
          type: number
          format: double
    Power:
      description: Power data in Watts
      properties:
        production:
          description: Power production of the site in Watts.
          $ref: "#/components/schemas/LiveValue"
        consumption:
          description: Power consumption of the site in Watts.
          $ref: "#/components/schemas/LiveValue"
      required:
        - production
    EnergyData:
      description: Includes all time energy in "allTime" and daily energy for the last 30 days in "daily". Energy values are in J (Joules, aka Watt-seconds).
      properties:
        allTime:
          type: number
          format: double
        daily:
          type: array
          items:
            $ref: "#/components/schemas/DateValue"
      required:
        - allTime
        - daily
    Energy:
      properties:
        production:
          $ref: "#/components/schemas/EnergyData"
      required:
        - production
    Storage:
      properties:
        stateOfEnergy:
          description: Average state of energy of the site's storage systems in the range [0, 1].
          $ref: "#/components/schemas/LiveValue"
        chargeRate:
          description: Total charge rate of the site's storage systems in Watts. If the system is discharging, the value will be negative.
          $ref: "#/components/schemas/LiveValue"
    SunriseSunset:
      description: >
        Includes sunrise/sunset information sufficient to draw sun position visualizations for any time of day.
        For example, in the early morning one can display sunsetYesterday and sunriseToday, and in the late night,
        sunsetToday and sunriseTomorrow.
      properties:
        sunsetYesterday:
          type: string
          format: date-time
        sunriseToday:
          type: string
          format: date-time
        sunsetToday:
          type: string
          format: date-time
        sunriseTomorrow:
          type: string
          format: date-time
    SiteMetadata:
      properties:
        name:
          type: string
          example: Test Site
        capacity:
          type: number
          format: double
          example: 1234.56
          description: Total capacity of the site in Watts (AC)
        status:
          $ref: "#/components/schemas/SiteWorkflowStatus"
        location:
          $ref: "#/components/schemas/Location"
      required:
        - name
        - capacity
        - location
    SiteData:
      properties:
        sunriseSunset:
          $ref: "#/components/schemas/SunriseSunset"
        meteo:
          $ref: "#/components/schemas/MeteoData"
        power:
          $ref: "#/components/schemas/Power"
        energy:
          $ref: "#/components/schemas/Energy"
        storage:
          $ref: "#/components/schemas/Storage"
      required:
        - power
        - energy
    PortfolioMetadata:
      properties:
        name:
          type: string
        description:
          type: string
        totalCapacity:
          type: number
          format: double
        sites:
          type: array
          description: List of site IDs for sites included in this portfolio
          items:
            type: string
      required:
        - name
        - totalCapacity
        - sites
    PortfolioData:
      properties:
        totalPower:
          $ref: "#/components/schemas/Power"
        totalEnergy:
          $ref: "#/components/schemas/Energy"
      required:
        - totalPower
        - totalEnergy
    Theme:
      properties:
        companyName:
          type: string
        companyLogoURL:
          type: string
          description: URL for the company logo image
        primaryColor:
          type: string
          description: 6 character hex string with octothorpe of the format "#abcdef"
        secondaryColor:
          type: string
          description: 6 character hex string with octothorpe of the format "#abcdef"
paths:
  /sites/{SiteID}/info:
    get:
      parameters:
        - $ref: "#/components/parameters/SiteID"
      operationId: getSiteInfo
      summary: Metadata about the requested site
      responses:
        "200":
          description: Site Metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SiteMetadata"
        "404":
          description: Site not found
  /sites/{SiteID}/data:
    get:
      parameters:
        - $ref: "#/components/parameters/SiteID"
      operationId: getSiteData
      summary: Data about the requested site
      responses:
        "200":
          description: Site Data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SiteData"
        "404":
          description: Site not found
  /sites/{SiteID}/theme:
    get:
      parameters:
        - $ref: "#/components/parameters/SiteID"
      operationId: getSiteTheme
      summary: Theme info for the requested site.
      responses:
        "200":
          description: Theme for the site
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Theme"
        "404":
          description: Site not found OR site does not have a theme
  /portfolios/{PortfolioID}/info:
    get:
      parameters:
        - $ref: "#/components/parameters/PortfolioID"
      operationId: getPortfolioInfo
      summary: Metadata about the requested portfolio
      responses:
        "200":
          description: Portfolio Metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortfolioMetadata"
        "404":
          description: Portfolio not found
  /portfolios/{PortfolioID}/data:
    get:
      parameters:
        - $ref: "#/components/parameters/PortfolioID"
      operationId: getPortfolioData
      summary: Live data about the requested portfolio
      responses:
        "200":
          description: Portfolio Data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PortfolioData"
        "404":
          description: Portfolio not found
  /portfolios/{PortfolioID}/theme:
    get:
      parameters:
        - $ref: "#/components/parameters/PortfolioID"
      operationId: getPortfolioTheme
      summary: Theme info for the requested portfolio.
      responses:
        "200":
          description: Theme for the portfolio
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Theme"
        "404":
          description: Portfolio not found OR portfolio does not have a theme