Verdigris Technologies Forecast API

openapi: 3.1.0
info:
  title: Data Control Forecast 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: Forecast
paths:
  /forecast/buildings:
    get:
      tags:
      - Forecast
      operationId: getBatchBuildingForecast
      summary: Batch building energy forecast
      description: 'Gets forecasted energy data for multiple buildings in a single batch request.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/buildingIds'
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      responses:
        '200':
          $ref: '#/components/responses/successForecast'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/entityNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntity'
components:
  parameters:
    buildingIds:
      in: query
      name: ids
      description: An array of building IDs separated by commas.
      required: true
      style: form
      explode: false
      schema:
        type: array
        items:
          type: integer
        minItems: 1
    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
    startTime:
      name: start_time
      in: query
      description: 'Start of the query time range. Must be [ISO 8601](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14) formatted.

        '
      required: true
      schema:
        type: string
        format: date-time
    endTime:
      name: end_time
      in: query
      description: 'End of the query time range. Must be [ISO 8601](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14) formatted.

        '
      required: true
      schema:
        type: string
        format: date-time
  schemas:
    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
    successForecastCSVISO8601:
      type: string
      example: 'id,timestamp,q1,q5,q10,q15,q20,q25,q30,q35,q40,q45,q50,q55,q60,q65,q70,q75,q80,q85,q90,q95,q99

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

        '
    successForecastJSONEpoch:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 12345
          timestamp:
            type: integer
            example: 1546301700000
          q1:
            type: number
            format: float
            example: 1337.314159
          q5:
            type: number
            format: float
            example: 1337.314159
          q10:
            type: number
            format: float
            example: 1337.314159
          q15:
            type: number
            format: float
            example: 1337.314159
          q20:
            type: number
            format: float
            example: 1337.314159
          q25:
            type: number
            format: float
            example: 1337.314159
          q30:
            type: number
            format: float
            example: 1337.314159
          q35:
            type: number
            format: float
            example: 1337.314159
          q40:
            type: number
            format: float
            example: 1337.314159
          q45:
            type: number
            format: float
            example: 1337.314159
          q50:
            type: number
            format: float
            example: 1337.314159
          q55:
            type: number
            format: float
            example: 1337.314159
          q60:
            type: number
            format: float
            example: 1337.314159
          q65:
            type: number
            format: float
            example: 1337.314159
          q70:
            type: number
            format: float
            example: 1337.314159
          q75:
            type: number
            format: float
            example: 1337.314159
          q80:
            type: number
            format: float
            example: 1337.314159
          q85:
            type: number
            format: float
            example: 1337.314159
          q90:
            type: number
            format: float
            example: 1337.314159
          q95:
            type: number
            format: float
            example: 1337.314159
          q99:
            type: number
            format: float
            example: 1337.314159
    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
    successForecastJSONISO8601:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            example: 12345
          timestamp:
            type: string
            format: date-time
            example: '2020-01-01T00:15:00Z'
          q1:
            type: number
            format: float
            example: 1337.314159
          q5:
            type: number
            format: float
            example: 1337.314159
          q10:
            type: number
            format: float
            example: 1337.314159
          q15:
            type: number
            format: float
            example: 1337.314159
          q20:
            type: number
            format: float
            example: 1337.314159
          q25:
            type: number
            format: float
            example: 1337.314159
          q30:
            type: number
            format: float
            example: 1337.314159
          q35:
            type: number
            format: float
            example: 1337.314159
          q40:
            type: number
            format: float
            example: 1337.314159
          q45:
            type: number
            format: float
            example: 1337.314159
          q50:
            type: number
            format: float
            example: 1337.314159
          q55:
            type: number
            format: float
            example: 1337.314159
          q60:
            type: number
            format: float
            example: 1337.314159
          q65:
            type: number
            format: float
            example: 1337.314159
          q70:
            type: number
            format: float
            example: 1337.314159
          q75:
            type: number
            format: float
            example: 1337.314159
          q80:
            type: number
            format: float
            example: 1337.314159
          q85:
            type: number
            format: float
            example: 1337.314159
          q90:
            type: number
            format: float
            example: 1337.314159
          q95:
            type: number
            format: float
            example: 1337.314159
          q99:
            type: number
            format: float
            example: 1337.314159
    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'
    successForecastCSVEpoch:
      type: string
      example: 'id,timestamp,q1,q5,q10,q15,q20,q25,q30,q35,q40,q45,q50,q55,q60,q65,q70,q75,q80,q85,q90,q95,q99

        12345,1546301700000,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159,1337.314159

        '
    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
  responses:
    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'
    successForecast:
      description: Forecasted energy data for one or more buildings.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/successForecastJSONEpoch'
            - $ref: '#/components/schemas/successForecastJSONISO8601'
        text/csv:
          schema:
            oneOf:
            - $ref: '#/components/schemas/successForecastCSVEpoch'
            - $ref: '#/components/schemas/successForecastCSVISO8601'
    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: {}