Cove.Tool Daylight Analysis API

openapi: 3.2.0
info:
  version: 2.0.0
  title: cove.tool REST API v2 Daylight Analysis API
  termsOfService: https://www.cove.tools/terms-of-use
  x-logo:
    url: ./covetool_logo.png
    altText: cove.tool logo
  description: '# Introduction

    The cove.tool API is a set of HTTP endpoints that help your app integrate with cove.tool. The cove.tool API is developed around the RESTful architecture


    Recently, we released the cove.tool API v2. The cove.tool API v2 includes a modern foundation, new and advanced features to how cove.tool can integrate seamlessly into your app.


    # Getting Started

    In order to start making calls to the API, each request will have to be authenticated. This is done by providing an authentication token on every request. It checks whether the user is authorized and has permission to perform the following actions. See more in Authentication section.

    1. **Cove.tool account** - Make sure to have access to a valid (trial/licensed) cove.tool account.

    2. **Projects created with cove.tool** - Once you login to your cove.tool account, make sure to create project(s) you wish to start making API requests with! As these are the projects that the API relies on to obtain, update and retrieve information.


    # Authentication

    By providing an authentication token on every request, it checks whether the user is authorized and has permission to update and retrieve data.

    ## Generating an API Token

    | URL | https://app.covetool.com/api/get-token |

    |-----|----------------------------------------|


    # Testing

    In order to understand how the cove.tool API can work for you, the easiest way is to start making requests! We recommend using standard API testing tools such as HTTPie or Postman to start interacting with the API over HTTP.


    # Error Codes

    | HTTP Status Code | Category |

    |:----------------:|:---------------------:|

    | 200 | OK |

    | 201 | Updated |

    | 202 | Accepted |

    | 400 | Bad Request |

    | 401 | Unauthorized Request |

    | 404 | Resource Not Found |

    | 5xx | Internal Server Error |


    _Happy Developing!_'
servers:
- url: https://app.covetool.com/api/v2
tags:
- name: Daylight Analysis
paths:
  /analysis:
    post:
      tags:
      - Daylight Analysis
      security:
      - apiKeyAuth: []
      summary: Kickstarts all analysis types for a given project
      description: Fires off the daylight analysis calculations to start running for a given project.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunDaylightAnalysisRequestBody'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunDaylightAnalysisResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
      operationId: postAnalysis
      x-operation-id-source: derived
  /analysis/{project_id}:
    get:
      tags:
      - Daylight Analysis
      security:
      - apiKeyAuth: []
      summary: Retrieves the results for daylight analysis for a given project
      parameters:
      - in: path
        required: true
        name: project_id
        schema:
          type: number
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DaylightAnalysisResultsResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
      operationId: getAnalysisByProjectId
      x-operation-id-source: derived
  /analysis/{project_id}/status:
    get:
      tags:
      - Daylight Analysis
      security:
      - apiKeyAuth: []
      summary: Obtains the remaining number of jobs per analysis type for a given project
      parameters:
      - in: path
        required: true
        name: project_id
        schema:
          type: number
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DaylightAnalysisStatusResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
      operationId: getAnalysisByProjectIdStatus
      x-operation-id-source: derived
  /analysis/{project_id}/stop:
    get:
      tags:
      - Daylight Analysis
      security:
      - apiKeyAuth: []
      summary: Halts all analyses calculations for a given project
      parameters:
      - in: path
        required: true
        name: project_id
        schema:
          type: number
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopDaylightAnalysisResponse'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getAnalysisByProjectIdStop
      x-operation-id-source: derived
components:
  schemas:
    StopDaylightAnalysisResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/GeneralEndpointResponses'
      - type: object
      example:
        data: null
        msg: All analyses were successfully halted.
        errors: {}
    DaylightAnalysisStatusResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/GeneralEndpointResponses'
      - type: object
      properties:
        data:
          $ref: '#/components/schemas/DaylightAnalysisStatusResponseData'
      example:
        data:
        - analysis: daylight
          jobs_total: 5
          jobs_remaining: 0
        - analysis: covid
          jobs_total: 5
          jobs_remaining: 0
        - analysis: lvc
          jobs_total: 5
          jobs_remaining: 0
        - analysis: radiation
          jobs_total: 6
          jobs_remaining: 0
        msg: Successfully retrieved resource.
        errors: {}
    RunDaylightAnalysisRequestBody:
      type: object
      required:
      - project_id
      - analysis_types
      properties:
        project_id:
          type: number
          example: 33
        analysis_types:
          type: array
          items:
            type: string
          example:
          - daylight
    DaylightAnalysisResultsResponseData:
      type: array
      items:
        type: object
        required:
        - run_id
        - building_type
        - floors
        - ase
        - sda
        properties:
          run_id:
            type: number
          building_type:
            type: string
          floors:
            type: array
            items:
              type: object
              required:
              - id
              - ase
              - sda
              properties:
                id:
                  type: number
                ase:
                  type: number
                  format: double
                sda:
                  type: number
                  format: double
          ase:
            type: number
            format: double
          sda:
            type: number
            format: double
    RunDaylightAnalysisResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/GeneralEndpointResponses'
      - type: object
      example:
        data: null
        msg: The analysis job was accepted.
        errors: {}
    GeneralEndpointResponses:
      type: object
      required:
      - data
      - msg
      - errors
      properties:
        data:
          type: object
        msg:
          type: string
        errors:
          type: array
          items:
            type: string
    DaylightAnalysisStatusResponseData:
      type: array
      items:
        type: object
        required:
        - analysis
        - jobs_total
        - jobs_remaining
        properties:
          analysis:
            type: string
          jobs_total:
            type: number
          jobs_remaining:
            type: number
    DaylightAnalysisResultsResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/GeneralEndpointResponses'
      - type: object
      properties:
        data:
          $ref: '#/components/schemas/DaylightAnalysisResultsResponseData'
      example:
        data:
        - run_id: 3
          building_type: Education
          floors:
          - id: 430
            ase: 10.891089108910892
            sda: 26.732673267326735
          ase: 10.891089108910892
          sda: 26.732673267326735
        msg: Successfully found results.
        errors: {}
  responses:
    BadRequest:
      description: Invalid request. Check contents of your response body.
    NotFound:
      description: The specified resource was not found. Verify if the URI is accurate.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
x-provenance:
  method: harvested
  publisher: Cove.Tool
  source: https://developers.covetool.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)