Verdigris Technologies Total Harmonic Distortion API

openapi: 3.1.0
info:
  title: Data Control Total Harmonic Distortion API
  description: Microservice that serves insightful power and energy data
  version: '1.1'
  contact:
    name: Verdigris Support
    email: support@verdigris.co
    url: https://docs.verdigris.co/
  termsOfService: https://verdigris.co/terms
servers:
- url: https://api.verdigris.co/data/v4
security:
- oauth2: []
tags:
- name: Total Harmonic Distortion
  description: Endpoints that return total harmonic distortion data
paths:
  /thd/panels:
    get:
      tags:
      - Total Harmonic Distortion
      operationId: getBatchPanelTHD
      summary: Batch panel total harmonic distortion
      description: 'Gets average total harmonic distortion data for multiple panels in a single batch request.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/panelIds'
      - $ref: '#/components/parameters/interval'
      - $ref: '#/components/parameters/intervalScopedStartTime'
      - $ref: '#/components/parameters/intervalScopedEndTime'
      - $ref: '#/components/parameters/timestampFormat'
      - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/successTotalHarmonicDistortion'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
  /thd/panels/{id}:
    get:
      tags:
      - Total Harmonic Distortion
      operationId: getPanelTotalHarmonicDistortion
      summary: Panel total harmonic distortion
      description: 'Gets average total harmonic distortion data for a panel.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/panelId'
      - $ref: '#/components/parameters/interval'
      - $ref: '#/components/parameters/intervalScopedStartTime'
      - $ref: '#/components/parameters/intervalScopedEndTime'
      - $ref: '#/components/parameters/timestampFormat'
      - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/successPowerFactor'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
components:
  schemas:
    successTotalHarmonicDistortionJSONEpoch:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 12345
          timestamp:
            type: integer
            example: 1546301700000
          power-factor:
            type: number
            format: float
            example: 0.025314352
    successTotalHarmonicDistortionCSVEpoch:
      type: string
      example: 'id,timestamp,power

        12345,1546301700000,0.025314352

        '
    permissionsInvalidError:
      type: object
      properties:
        name:
          type: string
          example: UnauthorizedError
        message:
          type: string
          example: Permissions should be an Array or String. Bad format?
        code:
          type: string
          example: permissions_invalid
        status:
          type: integer
          example: 403
    successPowerFactorJSONISO8601:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 12345
          timestamp:
            type: string
            format: date-time
            example: '2020-01-01T00:15:00Z'
          power-factor:
            type: number
            format: float
            example: 0.97233876
    successPowerFactorCSVEpoch:
      type: string
      example: 'id,timestamp,power

        12345,1546301700000,0.97233876

        '
    permissionDeniedError:
      type: object
      properties:
        name:
          type: string
          example: UnauthorizedError
        message:
          type: string
          example: Permission denied
        code:
          type: string
          example: permission_denied
        status:
          type: integer
          example: 403
    entityNotFoundError:
      type: object
      properties:
        name:
          type: string
          example: EntityNotFoundError
        message:
          type: string
          example: One or more entity with given IDs does not exist in your account.
        status:
          type: integer
          example: 404
        invalidIds:
          type: array
          items:
            type: integer
          example:
          - 1
          - 2
          - 3
    successPowerFactorCSVISO8601:
      type: string
      example: 'id,timestamp,power

        12345,2020-01-01T00:15:00Z,0.97233876

        '
    unauthorizedError:
      type: object
      properties:
        name:
          type: string
          example: UnauthorizedError
        message:
          type: string
          example: No authorization token was found
        code:
          type: string
          example: credentials_required
        status:
          type: integer
          example: 401
    unprocessableEntityError:
      type: object
      properties:
        name:
          type: string
          example: UnprocessableEntityError
        message:
          type: string
          example: Validation error
        status:
          type: integer
          example: 422
        errors:
          type: array
          items:
            $ref: '#/components/schemas/validationError'
    successPowerFactorJSONEpoch:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 12345
          timestamp:
            type: integer
            example: 1546301700000
          power-factor:
            type: number
            format: float
            example: 0.97233876
    validationError:
      type: object
      properties:
        location:
          type: string
          example: query
        msg:
          type: string
          example: must be in ISO 8601 format
        param:
          type: string
          example: start_time
        value:
          type: string
          example: 1:15PM 10/13/1999
    successTotalHarmonicDistortionJSONISO8601:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 12345
          timestamp:
            type: string
            format: date-time
            example: '2020-01-01T00:15:00Z'
          power-factor:
            type: number
            format: float
            example: 0.025314352
    successTotalHarmonicDistortionCSVISO8601:
      type: string
      example: 'id,timestamp,power

        12345,2020-01-01T00:15:00Z,0.025314352

        '
  parameters:
    interval:
      in: query
      name: interval
      description: 'Interval between each data points. Affects the validity of `start_time`, `end_time` query parameters, time resolution and aggregation of results.


        For example, given the time range query parameters, `start_time=2020-01-01T12:30:00Z&end_time=2020-01-01T13:00:00Z`:


        - `interval=1m`: returns 30 data points at minutely resolution.

        - `interval=15m`: returns 2 data points at 15-minutesly/quarter-hourly resolution.


        The ordering of timestamps is not guaranteed.

        '
      required: true
      schema:
        type: string
        enum:
        - 1m
        - 15m
        - 1h
        - 1d
        - 1M
    accept:
      in: header
      name: Accept
      description: 'Specify a [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml) to indicate the content type the client would like to receive the data in. If omitted, defaults to `application/json`.


        Currently, the supported formats are:


        - `application/json`

        - `text/csv`

        '
      required: false
      schema:
        type: string
        default: application/json
        enum:
        - application/json
        - text/csv
    intervalScopedStartTime:
      name: start_time
      in: query
      description: "Start of the query time range. Value must be in [ISO 8601](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14) format.\n\nNote that validity of `start_time` changes depending on the `interval` query parameter.\n\nFor example:\n\n- **VALID**: `start_time=2020-01-01T12:34:00Z&interval=1m`\n- **VALID**: `start_time=2020-01-01T12:45:00Z&interval=15m`\n- **VALID**: `start_time=2020-01-01T13:00:00Z&interval=1h`\n- **VALID** (if building’s timezone is in Pacific Standard Time):\n  - `start_time=2020-01-01T08:00:00Z&interval=1d` (UTC)\n  - `start_time=2020-01-01T00:00:00+08:00&interval=1d` (PST)\n- **NOT VALID**: `start_time=2020-01-01T12:34:00Z&interval=15m`\n- **NOT VALID**: `start_time=2020-01-01T12:59:00Z&interval=1h`\n- **NOT VALID** (if building’s timezone is in Pacific Standard Time):\n  - `start_time=2020-01-01T00:00:00Z&interval=1d`\n  - `start_time=2020-01-01T04:00:00+08:00&interval=1d`\n"
      required: true
      schema:
        type: string
        format: date-time
    intervalScopedEndTime:
      name: end_time
      in: query
      description: "End of the query time range. Value must be in [ISO 8601](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14) format.\n\nNote that validity of `end_time` changes depending on the `interval` query parameter.\n\nFor example:\n\n- **VALID**: `end_time=2020-12-31T12:34:00Z&interval=1m`\n- **VALID**: `end_time=2020-12-31T12:45:00Z&interval=15m`\n- **VALID**: `end_time=2020-12-31T13:00:00Z&interval=1h`\n- **VALID** (if building’s timezone is in Pacific Standard Time):\n  - `end_time=2020-12-31T08:00:00Z&interval=1d` (UTC)\n  - `end_time=2020-12-31T00:00:00+08:00&interval=1d` (PST)\n- **NOT VALID**: `end_time=2020-12-31T12:34:00Z&interval=15m`\n- **NOT VALID**: `end_time=2020-12-31T12:59:00Z&interval=1h`\n- **NOT VALID** (if building’s timezone is in Pacific Standard Time):\n  - `end_time=2020-12-31T00:00:00Z&interval=1d`\n  - `end_time=2020-12-31T04:00:00+08:00&interval=1d`\n"
      required: true
      schema:
        type: string
        format: date-time
    panelId:
      in: path
      name: id
      description: Panel ID
      required: true
      schema:
        type: integer
    timestampFormat:
      name: timestamp_format
      in: query
      description: 'Format timestamps in the data. If set to `ISO8601` (case-insensitive), the timestamp is returned as a string formatted in [ISO 8601](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14) format. If omitted, the timestamp is returned as an integer representing [UNIX epoch](https://en.wikipedia.org/wiki/Unix_time).

        '
      required: false
      schema:
        type: string
        nullable: true
        enum:
        - ISO8601
    panelIds:
      in: query
      name: ids
      description: An array of panel IDs separated by commas.
      required: true
      style: form
      explode: false
      schema:
        type: array
        items:
          type: integer
        minItems: 1
    timezone:
      name: timezone
      in: query
      description: "When used in conjunction with `timestamp_format` query parameter that is set to `ISO8601` format, specifying the [zone ID](https://nodatime.org/TimeZones) of [IANA Time Zone Database](https://www.iana.org/time-zones) returns the timestamp in the time zone offset.\n\nSetting the timezone when `timestamp_format` is not specified has no affect on the UNIX epoch timestamp.\n\n> \uD83D\uDCD8 Note\n>\n> This query parameter meant to be a convenience feature that only affects the _display format_ of the timestamps in the result. It has no affect on the building’s timezone.\n"
      required: false
      schema:
        type: string
        default: UTC
        format: zoneid
      examples:
        America/New_york:
          summary: US/Eastern
          value: America/New_york
        America/Chicago:
          summary: US/Central
          value: America/Chicago
        America/Denver:
          summary: US/Mountain
          value: America/Denver
        America/Los_angeles:
          summary: US/Pacific
          value: America/Los_angeles
        America/Anchorage:
          summary: US/Alaska
          value: America/Anchorage
        Pacific/Honolulu:
          summary: US/Hawaii
          value: Pacific/Honolulu
  responses:
    successPowerFactor:
      description: Average power factor data for given time range. The ordering of timestamps is not guaranteed.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/successPowerFactorJSONEpoch'
            - $ref: '#/components/schemas/successPowerFactorJSONISO8601'
        text/csv:
          schema:
            oneOf:
            - $ref: '#/components/schemas/successPowerFactorCSVEpoch'
            - $ref: '#/components/schemas/successPowerFactorCSVISO8601'
    successTotalHarmonicDistortion:
      description: Average total harmonic distortion for given time range. The ordering of timestamps is not guaranteed.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/successTotalHarmonicDistortionJSONEpoch'
            - $ref: '#/components/schemas/successTotalHarmonicDistortionJSONISO8601'
        text/csv:
          schema:
            oneOf:
            - $ref: '#/components/schemas/successTotalHarmonicDistortionCSVEpoch'
            - $ref: '#/components/schemas/successTotalHarmonicDistortionCSVISO8601'
    unprocessableEntity:
      description: One or more validations for request has failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/unprocessableEntityError'
    forbidden:
      description: Request to resource is forbidden due to insufficient permissions.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/permissionDeniedError'
            - $ref: '#/components/schemas/permissionsInvalidError'
    entityNotFound:
      description: Resource with given ID cannot be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/entityNotFoundError'
    unauthorized:
      description: 'Request to resource is unauthorized. This is likely due to missing access token in the `Authorization` header or an invalid token signature usually as a result of attempted token forgery by an unauthorized third-party.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/unauthorizedError'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.verdigris.co/oauth/token
          scopes: {}