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