openapi: 3.2.0
info:
title: Cove.tool Project Geometry API
termsOfService: https://www.cove.tools/terms-of-use
x-refined-note:
- x-apiVersions differs across the merged source definitions and was not carried
- x-logo differs across the merged source definitions and was not carried
version: '1.0'
description: 'Operations tagged Project Geometry across 2 of this provider''s published API definitions: cove.tool-api-v1-openapi.yml, cove.tool-rest-api-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.covetool.com/api
- url: https://app.covetool.com/api/v2
tags:
- name: Project Geometry
description: Update project geometry and obtain an Energy Use Intensity (EUI) breakdown of a given model.
paths:
/run-values:
post:
x-customPath:
name: /update-project-geometry
tags:
- Project Geometry
security:
- AuthToken: []
summary: Update geometry values for a given project/run
requestBody:
required: true
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Update3DGeometryAreasRequests'
- $ref: '#/components/schemas/Update2DGeometryAreasRequests'
responses:
'201':
description: Successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGeometryAreasResponses'
'400':
$ref: '#/components/responses/BadRequest'
description: "Update both 2D project geometry and 3D project geometry by passing in different request bodies. For more information on each of the required fields/categories, see the schemas in request body section of this endpoint.
\n2D and 3D project geometry both require at least one non-zero value in the **wall_area_X**, and **window_area_X** property (where **X** is the cardinal direction).\n
\n\n List of available cardinal directions (replace **X** with the following acceptable cardinal direction): \n - n\n - s\n - e\n - w\n - ne\n - nw\n - se\n - sw\n \n**3D Geometry**
Note that units should be in ft, so areas would be in ft2 regardless of project units. The _si_units_ parameter only affects the 2D geometry inputs.
Each category requires an array of objects represented as vertex and triangle data. Note that you can send each category separately. Each mesh must have a list of Vertices along with Triangles which refer to Vertices by index. Normal and Center are required for each mesh so that the faces are rendered in the correct direction/position. LevelId and DerivingElementUniqueId are optional fields.
\n**2D Geometry and 3D Geometry**
Note: All values will be converted to the project's units (in the web app interface) by default. This is controlled with the _si_units_ parameter - a value of true will save the values as SI while a value of false will convert them from imperial to SI before saving.
The EUI data in the response will always be in SI units."
x-codeSamples:
- lang: Python
name: Python
source: "import json, requests\n\nclass ApiHelpers:\n # Same credentials you use to log in to cove.tool\n def __init__(self, username, password):\n self.token = self._get_api_token(username, password)\n\n def post_request(self, path, data, use_token=True):\n url = self._api_url(path)\n headers = self._headers(use_token)\n response = requests.post(url, headers=headers, json=data)\n return self._handle_response(response)\n\n def get_request(self, path, use_token=True):\n url = self._api_url(path)\n headers = self._headers(use_token)\n response = requests.get(url, headers=headers)\n return self._handle_response(response)\n\n def _api_url(self, path):\n return 'https://app.covetool.com/api/' + path + '/'\n\n def _get_api_token(self, username, password):\n data = {\n 'username': username,\n 'password': password,\n }\n response_data = self.post_request('get-token', data, False)\n token = response_data['token']\n return str(token)\n\n def _headers(self, use_token):\n headers = {}\n if use_token:\n headers['Authorization'] = 'Token ' + self.token\n return headers\n\n def _handle_response(self, response):\n if response.ok:\n return response.json()\n else:\n return {'result': 'error'}\n\n# Set up helpers instance\nusername = 'username' # Replace with your cove.tool username\npassword = 'password' # Replace with your cove.tool password\nhelpers = ApiHelpers(username, password)\n\n# Update a run\n# Replace \"1\" with a run ID that belongs to one of your projects\nrun = 'https://app.covetool.com/api/runs/1/'\nsi_units = 'true'\nbuilding_height = 15\nroof_area = 900\nfloor_area = 900\nskylight_area = 150\nwall_area_e = 450\nwall_area_ne = 0\nwall_area_n = 450\nwall_area_nw = 0\nwall_area_w = 450\nwall_area_sw = 0\nwall_area_s = 450\nwall_area_se = 0\nwindow_area_e = 200\nwindow_area_ne = 0\nwindow_area_n = 200\nwindow_area_nw = 0\nwindow_area_w = 200\nwindow_area_sw = 0\nwindow_area_s = 200\nwindow_area_se = 0\n\ndata = {\n'run': run,\n'si_units': si_units,\n'building_height': building_height,\n'roof_area': roof_area,\n'floor_area': floor_area,\n'skylight_area': skylight_area,\n'wall_area_e': wall_area_e,\n'wall_area_ne': wall_area_ne,\n'wall_area_n': wall_area_n,\n'wall_area_nw': wall_area_nw,\n'wall_area_w': wall_area_w,\n'wall_area_sw': wall_area_sw,\n'wall_area_s': wall_area_s,\n'wall_area_se': wall_area_se,\n'window_area_e': window_area_e,\n'window_area_ne': window_area_ne,\n'window_area_n': window_area_n,\n'window_area_nw': window_area_nw,\n'window_area_w': window_area_w,\n'window_area_sw': window_area_sw,\n'window_area_s': window_area_s,\n'window_area_se': window_area_se,\n}\n\nresult = helpers.post_request('run-values', data)\neui_total = result['data']['eui_total']\nprint('EUI Total:', eui_total)\n\ncooling = 0\nheating = 0\nlighting = 0\nequipment = 0\nfans = 0\npumps = 0\nhot_water = 0\neui_breakdown = result['data']['eui_breakdown']\nheaders = eui_breakdown['headers']\nvalues = eui_breakdown['values']\nfor i, header in enumerate(headers):\n if header == 'Cooling':\n cooling = float(values[i])\n print('Cooling:', cooling)\n elif header == 'Heating':\n heating = float(values[i])\n print('Heating:', heating)\n elif header == 'Lighting':\n lighting = float(values[i])\n print('Lighting:', lighting)\n elif header == 'Equipment':\n equipment = float(values[i])\n print('Equipment:', equipment)\n elif header == 'Fans':\n fans = float(values[i])\n print('Fans:', fans)\n elif header == 'Pumps':\n pumps = float(values[i])\n print('Pumps:', pumps)\n elif header == 'Hot Water':\n hot_water = float(values[i])\n print('Hot Water:', hot_water)\n"
servers:
- url: https://app.covetool.com/api
/projects/{project_id}/geometry:
post:
tags:
- Project Geometry
security:
- apiKeyAuth: []
summary: Updates a project's 3D geometry
description: 'Gives you the ability to update a project''s 3D geometry that will be utilized to perform Daylight Analysis with analysis.tool.
Updating project geometry requires at least *one* non-zero value in the **wall_area_X**, and **window_area_X** property (where **X** is the cardinal direction).'
parameters:
- in: path
required: true
name: project_id
schema:
type: number
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Update3DGeometryRequestBody'
responses:
'201':
description: Successfully Created
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGeometryAreasResponses_2'
'400':
$ref: '#/components/responses/BadRequest_2'
servers:
- url: https://app.covetool.com/api/v2
components:
schemas:
UpdateGeometryAreasResponses:
type: object
required:
- data
- result
properties:
data:
type: object
required:
- eui_breakdown
- eui_total
properties:
eui_breakdown:
type: object
required:
- headers
- values
- total_gas
- total_electric
- total_electric_without_pv
- Primary Energy Heating
- Primary Energy Domestic Hot Water
properties:
headers:
$ref: '#/components/schemas/EuiBreakdownHeaders'
values:
type: array
items:
type: number
format: double
example:
- 42.69810373890001
- 215.9911661803
- 35.150749997999995
- 26.540714283
- 83.00345598700001
- 4.380000116000001
- 5.9237200512
total_gas:
type: number
format: double
example: 10.4080428009
total_electric:
type: number
format: double
example: 174.19649714809515
Primary Energy Heating:
type: string
example: electric
Primary Energy Domestic Hot Water:
type: string
example: gas
eui_total:
type: number
format: double
example: 413.68791035439995
result:
type: string
format: string
example: success
Update2DGeometryAreasRequests:
type: object
required:
- run
- building_height
- roof_area
- floor_area
properties:
run:
type: string
format: url
example: https://app.covetool.com/api/runs/1
window_area_ne:
type: number
minimum: 0
example: 0
roof_area:
type: number
minimum: 0
example: 900
skylight_area:
type: number
minimum: 0
example: 150
building_height:
type: number
minimum: 0
example: 15
window_area_nw:
type: number
minimum: 0
example: 0
window_area_se:
type: number
minimum: 0
example: 0
window_area_sw:
type: number
minimum: 0
example: 0
si_units:
type: boolean
example: true
floor_area:
type: number
minimum: 0
example: 900
wall_area_sw:
type: number
minimum: 0
example: 0
wall_area_nw:
type: number
minimum: 0
example: 0
wall_area_ne:
type: number
minimum: 0
example: 0
wall_area_se:
type: number
minimum: 0
example: 0
window_area_e:
type: number
minimum: 0
example: 200
wall_area_w:
type: number
minimum: 0
example: 450
wall_area_s:
type: number
minimum: 0
example: 450
window_area_n:
type: number
minimum: 0
example: 200
wall_area_n:
type: number
minimum: 0
example: 450
window_area_s:
type: number
minimum: 0
example: 200
window_area_w:
type: number
minimum: 0
example: 200
wall_area_e:
type: number
minimum: 0
example: 450
MeshObject:
description: An array of objects represented as vertex and triangle data. Each mesh must have a list of Vertices along with Triangles which refer to Vertices by index. Normal and Center are required for each mesh so that the faces are rendered in the correct direction/position. LevelId and DerivingElementUniqueId are optional fields
type: array
items:
type: object
required:
- Mesh
- Center
- Normal
properties:
Mesh:
type: object
required:
- Vertices
- Triangles
properties:
Vertices:
$ref: '#/components/schemas/VerticesObject'
Triangles:
$ref: '#/components/schemas/TrianglesArray'
Center:
$ref: '#/components/schemas/CenterObject'
Normal:
$ref: '#/components/schemas/NormalObject'
VerticesObject:
type: object
allOf:
- $ref: '#/components/schemas/VerticesModel'
- type: object
example:
- X: 0.666022
Y: 226.752487
Z: 25.262917
- X: 0.66602
Y: 50.666023
Z: 25.262917
- X: 27.935207
Y: 50.666023
Z: 26.262917
- X: 27.935207
Y: 66.381523
Z: 25.262917
- X: 36.596779
Y: 66.281523
Z: 25.262917
- X: 36.596779
Y: 50.66023
Z: 25.262917
- X: 208.763153
Y: 50.666023
Z: 25.262917
- X: 208.763153
Y: 66.281523
Z: 25.262917
- X: 217.424728
Y: 66.381523
Z: 25.262917
- X: 217.424728
Y: 86.249985
Z: 25.262917
- X: 56.250347
Y: 86.249985
Z: 25.262917
- X: 56.250347
Y: 191.08519
Z: 25.262917
- X: 121.751503
Y: 191.08519
Z: 25.262917
- X: 121.751503
Y: 211.036987
Z: 25.262917
- X: 113.089935
Y: 211.036987
Z: 25.262917
- X: 113.089935
Y: 226.752487
Z: 25.262917
- X: 62.055077
Y: 70.138153
Z: 25.262917
- X: 62.055077
Y: 77.27903
Z: 25.262917
- X: 68.170013
Y: 77.27903
Z: 25.262917
- X: 68.170013
Y: 70.138153
Z: 25.262917
- X: 36.45314
Y: 112.458786
Z: 25.262917
- X: 45.705929
Y: 112.458786
Z: 25.262917
- X: 45.705929
Y: 86.458328
Z: 25.262917
- X: 36.45314
Y: 86.458328
Z: 25.262917
- X: 36.45314
Y: 148.459427
Z: 25.262917
- X: 45.705929
Y: 148.459427
Z: 25.262917
- X: 45.705929
Y: 122.458969
Z: 25.262917
- X: 36.45314
Y: 122.458969
Z: 25.262917
- X: 36.519417
Y: 184.460068
Z: 25.262917
- X: 45.673122
Y: 184.460068
Z: 25.262917
- X: 45.673122
Y: 158.45961
Z: 25.262917
- X: 36.519417
Y: 158.45961
Z: 25.262917
NormalObject:
allOf:
- $ref: '#/components/schemas/VerticesModel'
- type: object
example:
X: 0
Y: 0
Z: 1
EuiBreakdownHeaders:
type: array
items:
type: string
example:
- Cooling
- Heating
- Lighting
- Equipment
- Fans
- Pumps
- Hot Water
Update3DGeometryAreasRequests:
type: object
required:
- source
- run
- walls
- windows
- roofs
- floors
- building_height
properties:
run:
type: string
example: https://app.covetool.com/api/runs/1
source:
description: Your app name and version identifier
type: string
example: revit-2.2.0
building_height:
type: number
example: 15
window_area_ne:
type: number
example: 200
wall_area_e:
type: number
example: 450
walls:
note: refers to exterior walls
allOf:
- $ref: '#/components/schemas/MeshObject'
windows:
allOf:
- $ref: '#/components/schemas/MeshObject'
roofs:
allOf:
- $ref: '#/components/schemas/MeshObject'
floors:
allOf:
- $ref: '#/components/schemas/MeshObject'
rotation_angle:
description: The rotation angle in degrees from North in a clockwise direction
type: number
example: 45
interior_walls:
allOf:
- $ref: '#/components/schemas/MeshObject'
skylights:
allOf:
- $ref: '#/components/schemas/MeshObject'
shading_devices:
allOf:
- $ref: '#/components/schemas/MeshObject'
spandrels:
allOf:
- $ref: '#/components/schemas/MeshObject'
outdoor_floors:
allOf:
- $ref: '#/components/schemas/MeshObject'
furniture:
allOf:
- $ref: '#/components/schemas/MeshObject'
below_grade_walls:
allOf:
- $ref: '#/components/schemas/MeshObject'
CenterObject:
allOf:
- $ref: '#/components/schemas/VerticesModel'
- type: object
example:
X: 72.45084
Y: 119.337007
Z: 25.262917
TrianglesArray:
allOf:
- type: array
example:
- - 1
- 2
- 3
- - 31
- 28
- 0
- - 31
- 0
- 24
- - 29
- 11
- 28
- - 27
- 24
- 1
- - 1
- 20
- 27
- - 24
- 25
- 31
- - 20
- 21
- 26
- - 0
- 1
- 24
- - 11
- 29
- 30
- - 12
- 13
- 14
- - 15
- 11
- 14
- - 12
- 14
- 11
- - 0
- 11
- 15
- - 26
- 21
- 10
- - 26
- 10
- 25
- - 11
- 30
- 25
- - 25
- 10
- 11
- - 4
- 22
- 23
- - 1
- 3
- 23
- - 18
- 9
- 10
- - 10
- 22
- 17
- - 3
- 4
- 23
- - 4
- 17
- 22
- - 1
- 2
- 3
- - 1
- 23
- 20
- - 5
- 16
- 4
- - 4
- 16
- 17
- - 18
- 7
- 9
- - 17
- 18
- 10
- - 7
- 19
- 6
- - 5
- 9
- 16
- - 7
- 8
- 9
- - 19
- 7
- 18
- - 19
- 5
- 6
- - 22
- 10
- 21
- - 25
- 30
- 31
- - 20
- 26
- 27
VerticesModel:
type: object
properties:
X:
type: number
format: double
Y:
type: number
format: double
Z:
type: number
format: double
Update3DGeometryRequestBody:
type: object
required:
- floors
- walls
- windows
- roofs
- floor_area
- roof_area
- ground_floor_area
- building_height
- si_units
properties:
floors:
allOf:
- $ref: '#/components/schemas/MeshObject_2'
walls:
allOf:
- $ref: '#/components/schemas/MeshObject_2'
windows:
allOf:
- $ref: '#/components/schemas/MeshObject_2'
roofs:
allOf:
- $ref: '#/components/schemas/MeshObject_2'
floor_area:
type: number
format: double
example: 37.21
roof_area:
type: number
format: double
example: 37.21
ground_floor_area:
type: number
format: double
example: 37.21
building_height:
type: number
example: 4.115
si_units:
type: boolean
example: true
below_grade_walls:
allOf:
- $ref: '#/components/schemas/MeshObject_2'
outdoor_floors:
allOf:
- $ref: '#/components/schemas/MeshObject_2'
interior_walls:
allOf:
- $ref: '#/components/schemas/MeshObject_2'
spandrels:
allOf:
- $ref: '#/components/schemas/MeshObject_2'
skylights:
allOf:
- $ref: '#/components/schemas/MeshObject_2'
shading_devices:
allOf:
- $ref: '#/components/schemas/MeshObject_2'
skylight_area:
type: number
format: double
example: 0
underground_area:
type: number
format: double
example: 0
rooms:
$ref: '#/components/schemas/RoomsMeshObject'
wall_area_n:
type: number
format: double
example: 23.707
wall_area_ne:
type: number
format: double
example: 0
wall_area_e:
type: number
format: double
example: 25.1
wall_area_se:
type: number
format: double
example: 0
wall_area_s:
type: number
format: double
example: 23.707
wall_area_sw:
type: number
format: double
example: 0
wall_area_w:
type: number
format: double
example: 23.158
wall_area_nw:
type: number
format: double
example: 0
window_area_n:
type: number
format: double
example: 1.394
window_area_ne:
type: number
format: double
example: 0
window_area_e:
type: number
format: double
example: 0
window_area_se:
type: number
format: double
example: 0
window_area_s:
type: number
format: double
example: 1.394
window_area_sw:
type: number
format: double
example: 0
window_area_w:
type: number
format: double
example: 0
window_area_nw:
type: number
format: double
example: 0
roof_u_value:
type: number
format: double
example: 0.183
ground_floor_u_value:
type: number
format: double
example: 0.17600000000000002
skylight_u_value:
type: number
format: double
example: 2.84
skylight_shgc:
type: number
format: double
example: 0.4
window_u_value_n:
type: number
format: double
example: 0.38
wall_u_value_n:
type: number
format: double
example: 0.3132
basement_depth:
type: number
example: 0
UpdateGeometryAreasResponses_2:
type: object
allOf:
- $ref: '#/components/schemas/GeneralEndpointResponses'
properties:
data:
type: object
required:
- eui
- eui_breakdown
- floors_count
- triangles_count
properties:
eui_breakdown:
type: object
required:
- headers
- values
- total_gas
- total_electric
- total_electric_without_pv
- Primary Energy Heating
- Primary Energy Domestic Hot Water
properties:
headers:
$ref: '#/components/schemas/EuiBreakdownHeaders'
values:
type: array
items:
type: number
format: double
example:
- 42.69810373890001
- 215.9911661803
- 35.150749997999995
- 26.540714283
- 83.00345598700001
- 4.380000116000001
- 5.9237200512
total_gas:
type: number
format: double
example: 10.4080428009
total_electric:
type: number
format: double
example: 174.19649714809515
total_electric_without_pv:
type: number
format: double
example: 3602.852278444
Primary Energy Heating:
type: string
example: electric
Primary Energy Domestic Hot Water:
type: string
example: gas
floors_count:
type: number
example: 5
triangles_count:
type: number
example: 34
example:
data:
eui: 3707.0816073715214
eui_breakdown:
values:
- 42.69810373890001
- 215.9911661803
- 35.150749997999995
- 26.540714283
- 83.00345598700001
- 4.380000116000001
- 5.9237200512
headers:
- Cooling
- Heating
- Lighting
- Equipment
- Fans
- Pumps
- Hot Water
total_gas: 104.22932892752092
total_electric: 3602.852278444
total_electric_without_pv: 3602.852278444
Primary Energy Heating: 0
Primary Energy Domestic Hot Water: 0
floors_count: 5
triangles_count: 34
MeshObject_2:
type: array
items:
type: object
required:
- Mesh
- Center
- Normal
properties:
Mesh:
type: object
required:
- Vertices
- Triangles
properties:
Vertices:
$ref: '#/components/schemas/VerticesObject_2'
Triangles:
$ref: '#/components/schemas/TrianglesArray_2'
Center:
$ref: '#/components/schemas/CenterObject'
Normal:
$ref: '#/components/schemas/NormalObject'
GeneralEndpointResponses:
type: object
required:
- data
- msg
- errors
properties:
data:
type: object
msg:
type: string
errors:
type: array
items:
type: string
VerticesObject_2:
type: object
allOf:
- $ref: '#/components/schemas/VerticesModel'
- type: object
example:
- X: 0.666022
Y: 226.752487
Z: 25.262917
- X: 0.66602
Y: 50.666023
Z: 25.262917
RoomsMeshObject:
type: object
required:
- rooms
- Windows
properties:
rooms:
type: array
items:
type: object
required:
- Faces
- area
- volume
- roomId
- name
- number
- levelName
- levelId
properties:
Faces:
type: array
items:
type: object
required:
- Mesh
properties:
Mesh:
$ref: '#/components/schemas/MeshObjectV2'
areaIDs:
type: array
items:
type: string
format: uuid
area:
type: number
format: double
example: 37.21
Center:
allOf:
- $ref: '#/components/schemas/CenterObject'
Normal:
allOf:
- $ref: '#/components/schemas/NormalObject'
type:
type: string
example: Floor
roofId:
type: string
format: uuid
example: 84c72356-bc7b-4c95-a9bc-b6a676206957
roofArea:
type: number
format: double
example: 37.21
floorId:
type: string
format: uuid
example: 69f0a2a8-2160-4294-a909-a9977d9d67b3
obc:
type: string
example: Ground
area:
type: number
format: double
example: 37.21
volume:
type: number
format: double
example: 15311.170800000002
roomId:
type: string
format: uuid
example: db20906a-731d-4dfd-9103-29593575b05c
name:
type: string
example: Room
number:
type: number
example: 1
levelName:
type: string
example: Floor 1
levelId:
type: string
format: uuid
example: 78c93975-070c-4219-bcae-3be319b3cfce
Windows:
type: array
items:
type: object
required:
- Center
- Normal
- Mesh
- area
- holeId
properties:
Center:
allOf:
- $ref: '#/components/schemas/CenterObject'
Normal:
allOf:
- $ref: '#/components/schemas/NormalObject'
Mesh:
required:
- Vertices
- Triangles
- wallId
properties:
Vertices:
type: array
items:
type: object
allOf:
- $ref: '#/components/schemas/VerticesObject_2'
Triangles:
type: array
items:
allOf:
- $ref: '#/components/schemas/TrianglesArray_2'
wallId:
type: string
format: uuid
example: 097c40f5-b020-4017-8888-f252e1ce4e0b
area:
type: number
format: double
holeId:
type: string
format: uuid
TrianglesArray_2:
allOf:
- type: array
example:
- - 1
- 2
- 3
- - 31
- 28
- 0
MeshObjectV2:
type: object
required:
- Vertices
- Triangles
properties:
Vertices:
$ref: '#/components/schemas/VerticesObject_2'
Triangles:
$ref: '#/components/schemas/TrianglesArray_2'
responses:
BadRequest:
description: Bad/Invalid request
BadRequest_2:
description: Invalid request. Check contents of your response body.
securitySchemes:
AuthToken:
type: apiKey
in: header
name: Authorization
apiKeyAuth:
type: apiKey
in: header
name: Authorization
x-refined-from:
- cove.tool-api-v1-openapi.yml
- cove.tool-rest-api-v2-openapi.yml
x-tagGroups:
- name: Authentication
tags:
- Authentication Header
- Authentication Token
- name: Projects
tags:
- Projects
- Project Geometry