openapi: 3.2.0
info:
  title: Wattwatchers Long Energy API
  description: API for accessing Wattwatchers data and functionality
  contact:
    name: Wattwatchers Support
    url: https://service.wattwatchers.com.au/kb-tickets/new
    email: support@wattwatchers.com.au
  version: 3.6.0
servers:
- description: Wattwatchers API v3
  url: https://api-v3.wattwatchers.com.au
tags:
- name: Long Energy
  description: Operations related to Long Energy (LE)
paths:
  /long-energy/{device-id}:
    get:
      tags:
      - Long Energy
      summary: Get long energy data for a device
      description: Returns the energy data for a single device.
      operationId: getLongEnergyData
      parameters:
      - $ref: '#/components/parameters/deviceId'
      - $ref: '#/components/parameters/fromTsLong'
      - $ref: '#/components/parameters/toTsLong'
      - $ref: '#/components/parameters/granularity'
      - $ref: '#/components/parameters/timezone'
      - $ref: '#/components/parameters/filterGroup'
      - $ref: '#/components/parameters/convertEnergy'
      - $ref: '#/components/parameters/fieldsEnergyPF'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LongEnergyData'
              example:
              - timestamp: 1550408400
                duration: 900
                eReal:
                - 3639405
                - 336898
                - -560
                - 37
                - -14
                - -25
                eRealNegative:
                - 0
                - 0
                - 560
                - 0
                - 14
                - 25
                eRealPositive:
                - 3639405
                - 336898
                - 0
                - 37
                - 0
                - 0
                eReactive:
                - 154581
                - 140216
                - 61
                - 45
                - -4
                - 11
                eReactiveNegative:
                - 13832
                - 0
                - 0
                - 0
                - 5
                - 0
                eReactivePositive:
                - 168413
                - 140216
                - 61
                - 45
                - 1
                - 11
                vRMSMin:
                - 229.4
                - 229.5
                - 229.6
                - 229.4
                - 229.5
                - 229.6
                vRMSMax:
                - 232.2
                - 232.4
                - 232.4
                - 232.2
                - 232.4
                - 232.5
                iRMSMin:
                - 14.799
                - 0.331
                - 0.023
                - 0.023
                - 0.023
                - 0.022
                iRMSMax:
                - 21.208
                - 4.534
                - 0.043
                - 0.046
                - 0.043
                - 0.042
        '204':
          description: No Content - No energy data has been received from the device
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: BAD_REQUEST
                httpCode: 400
                message: You must specify a valid timezone value when applying granularity of 'hour', 'day', 'week', or 'month.'
        '422':
          description: Unprocessable Entity - Period is greater than valid values for granularity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: UNPROCESSABLE_ENTITY
                httpCode: 422
                message: The requested time period is greater than 7 days.
      security:
      - BearerAuth: []
  /long-energy/{device-id}/first:
    get:
      tags:
      - Long Energy
      summary: Get first long energy data entry
      description: Returns the first received long energy entry from the device.
      operationId: getFirstLongEnergyData
      parameters:
      - $ref: '#/components/parameters/deviceId'
      - $ref: '#/components/parameters/filterGroup'
      - $ref: '#/components/parameters/convertEnergy'
      - $ref: '#/components/parameters/fieldsEnergyPFAndTimestamp'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LongEnergyDataPoint'
              examples:
                default:
                  $ref: '#/components/examples/LongEnergyDataPoint'
                withTimestampOnly:
                  $ref: '#/components/examples/FirstLastTimestampOnly'
        '204':
          description: No Content - No energy data has been received from the device
      security:
      - BearerAuth: []
  /long-energy/{device-id}/latest:
    get:
      tags:
      - Long Energy
      summary: Get latest long energy data entry
      description: Returns the latest received long energy entry from the device.
      operationId: getLatestLongEnergyData
      parameters:
      - $ref: '#/components/parameters/deviceId'
      - $ref: '#/components/parameters/filterGroup'
      - $ref: '#/components/parameters/convertEnergy'
      - $ref: '#/components/parameters/fieldsEnergyPFAndTimestamp'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LongEnergyDataPoint'
              examples:
                default:
                  $ref: '#/components/examples/LongEnergyDataPoint'
                withTimestampOnly:
                  $ref: '#/components/examples/FirstLastTimestampOnly'
        '204':
          description: No Content - No energy data has been received from the device
      security:
      - BearerAuth: []
components:
  parameters:
    toTsLong:
      name: toTs
      in: query
      required: false
      schema:
        type: integer
      example: 1546956000
      description: Unix timestamp, seconds since epoch. Returns data with timestamp < toTs. Default, if not specified = 7 days after fromTs.
    granularity:
      name: granularity
      in: query
      required: false
      schema:
        type: string
        enum:
        - 5m
        - 15m
        - 30m
        - hour
        - day
        - week
        - month
      example: 5m
      description: Granularity of the data.
    fieldsEnergyPF:
      name: fields[energy]
      in: query
      required: false
      schema:
        type: string
        enum:
        - +pf
      example: +pf
      description: \'+pf\' will append calculated power factor to the returned energy data objects. Note that filter[group]=phases can't be combined with fields[energy]=+pf.
    filterGroup:
      name: filter[group]
      in: query
      required: false
      schema:
        type: string
        enum:
        - phases
      example: phases
      description: When set to 'phases', the energy data entries will be collapsed to reflect the phases.grouping configuration of the device.
    convertEnergy:
      name: convert[energy]
      in: query
      required: false
      schema:
        type: string
        enum:
        - kWh
        - kW
      example: kWh
      description: Converts energy data to kilowatt hours or kilowatts.
    deviceId:
      name: device-id
      in: path
      required: true
      schema:
        type: string
      description: The ID of the device
      example: D123456789012
    fieldsEnergyPFAndTimestamp:
      name: fields[energy]
      in: query
      required: false
      schema:
        type: string
        enum:
        - +pf
        - timestamp
      example: +pf
      description: \`fields[energy]=+pf\` will append calculated power factor to the returned energy data objects. \`timestamp\` will return just the timestamp attribute in the returned data object. +pf and timestamp are mutually exclusive and can't be combined, i.e. fields[energy]=+pf,timestamp will result in an error. The fields[energy] query string options can't be combined with filter[group]=phases.
    fromTsLong:
      name: fromTs
      in: query
      required: false
      schema:
        type: integer
      example: 1546952400
      description: Unix timestamp, seconds since epoch. Returns data with timestamp >= fromTs. Default, if not specified = first long energy entry.
    timezone:
      name: timezone
      in: query
      required: false
      schema:
        type: string
      example: Australia/Sydney
      description: Required if granularity >= hour. Irrelevant (and ignored) if granularity is < hour.
  schemas:
    LongEnergyDataPoint:
      title: Long Energy data point
      description: A Long Energy data point
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp in seconds
          example: 1550622130
        duration:
          type: integer
          format: int64
          description: Interval duration in seconds
          example: 300
        eReal:
          type: array
          items:
            type: number
            format: float
            description: Real Energy value for a device channel
            example: 3639405
          description: Real Energy values for each device channel
          example:
          - 3639405
          - 336898
          - -560
          - 37
          - -14
          - -25
        eRealNegative:
          type: array
          items:
            type: number
            format: float
            description: Negative Real Energy value for a device channel
            example: 560
          description: Negative Real Energy values for each device channel. Over the Long Energy period there may be points of negative energy (e.g. exports to the grid) that are "hidden" in the `eReal` value for the period if the overall total is positive. `eRealNegative` enables you to determine the total negative flows during the period
          example:
          - 0
          - 0
          - 560
          - 0
          - 14
          - 25
        eRealPositive:
          type: array
          items:
            type: number
            format: float
            description: Positive Real Energy value for a device channel. Over the Long Energy period there may be points of negative energy (e.g. drawing energy from the grid) that are "hidden" in the `eReal` value for the period if the overall total is negative (for example if solar generation results in an overall export for the period). `eRealPositive` enables you to determine the total positive flows during the period
            example: 3639405
          description: Positive Real Energy values for each device channel
          example:
          - 3639405
          - 336898
          - 0
          - 37
          - 0
          - 0
        eReactive:
          type: array
          items:
            type: number
            format: float
            description: Reactive Energy value for a device channel
            example: 154581
          description: Reactive Energy values for each device channel
          example:
          - 154581
          - 140216
          - 61
          - 45
          - -4
          - 11
        eReactiveNegative:
          type: array
          items:
            type: number
            format: float
            description: Negative Reactive Energy value for a device channel
            example: 13832
          description: Negative Reactive Energy values for each device channel
          example:
          - 13832
          - 0
          - 0
          - 0
          - 5
          - 0
        eReactivePositive:
          type: array
          items:
            type: number
            format: float
            description: Positive Reactive Energy value for a device channel
            example: 168413
          description: Positive Reactive Energy values for each device channel
          example:
          - 168413
          - 140216
          - 61
          - 45
          - 1
          - 11
        vRMSMin:
          type: array
          description: Minimum Volts RMS values for each device channel
          items:
            type: number
            format: float
            description: Minimum Volts RMS value for a device channel. As voltage is an instantaneous value, only the minimum and maximum that occurred within the period are reported for Long Energy.
            example: 244.9
          example:
          - 229.4
          - 229.5
          - 229.6
          - 229.4
          - 229.5
          - 229.6
        vRMSMax:
          type: array
          description: Maximum Volts RMS values for each device channel
          items:
            type: number
            format: float
            description: Maximum Volts RMS value for a device channel. As voltage is an instantaneous value, only the minimum and maximum that occurred within the period are reported for Long Energy.
            example: 232.2
          example:
          - 232.2
          - 232.4
          - 232.4
          - 232.2
          - 232.4
          - 232.5
        iRMSMin:
          type: array
          description: Minimum Current RMS values for each device channel
          items:
            type: number
            format: float
            description: Minimum Current RMS value for a device channel. As current is an instantaneous value, only the minimum and maximum that occurred within the period are reported for Long Energy.
            example: 0.023
          example:
          - 14.799
          - 0.331
          - 0.023
          - 0.023
          - 0.023
          - 0.022
        iRMSMax:
          type: array
          description: Maximum Current RMS values for each device channel
          items:
            type: number
            format: float
            description: Maximum Current RMS value for a device channel. As current is an instantaneous value, only the minimum and maximum that occurred within the period are reported for Long Energy.
            example: 0.023
          example:
          - 21.208
          - 4.534
          - 0.043
          - 0.046
          - 0.043
          - 0.042
    LongEnergyData:
      title: Long Energy data
      description: An array of Long Energy data points
      type: array
      items:
        $ref: '#/components/schemas/LongEnergyDataPoint'
    Error:
      title: Error response
      description: Error object
      type: object
      properties:
        code:
          description: Error code
          type: string
          example: Unauthorized
        httpCode:
          description: HTTP error code
          type: integer
          example: 401
        message:
          description: Error message
          type: string
          example: API key is missing or invalid.
  examples:
    FirstLastTimestampOnly:
      value:
        timestamp: 1550622145
    LongEnergyDataPoint:
      description: A Long Energy data point
      value:
        timestamp: 1550622145
        duration: 900
        eReal:
        - 3586031
        - 329486
        - -549
        - 39
        - -13
        - -24
        eRealNegative:
        - 0
        - 0
        - 549
        - 0
        - 13
        - 24
        eRealPositive:
        - 3586031
        - 329486
        - 0
        - 39
        - 0
        - 0
        eReactive:
        - 134087
        - 136446
        - 47
        - 33
        - -10
        - 11
        eReactiveNegative:
        - 11739
        - 0
        - 0
        - 0
        - 10
        - 0
        eReactivePositive:
        - 145826
        - 136446
        - 47
        - 33
        - 0
        - 11
  securitySchemes:
    BearerAuth:
      description: Bearer token authentication
      type: http
      scheme: bearer