The cove.tool REST API can be used to upload your project's geometry and get an EUI breakdown. In this article we will go through a basic example using HTTPie. At the end of the article you will see some additional examples using Python and C#.

There are 3 basic objects: projects, runs, and run values. A project has many runs, and a run has many run values. The "unique ID" is the url  which must be included when updating an object.

Obtain an API token

request

http POST https://app.covetool.com/api/get-token/ username=username password=password

response

{ "token": "aaaa1111aaaa1111aaaa1111aaaa1111aaaa" }

List all projects

request

http GET https://app.covetool.com/api/projects/ "Authorization: Token aaaa1111aaaa1111aaaa1111aaaa1111aaaa"

response

[
    {
        "name": "Project A",
        "run_set": [
            "https://app.covetool.com/api/runs/1/"
        ],
        "url": "https://app.covetool.com/api/projects/1/"
    },
    {
        "name": "Project B",
        "run_set": [
            "https://app.covetool.com/api/runs/2/"
        ],
        "url": "https://app.covetool.com/api/projects/2/"
    }
]

Update geometry for a given project/run 

Note that all values will be converted to the project's units (in the web app interface) by default. This can be 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. 

request

http POST https://app.covetool.com/api/run-values/ run='https://app.covetool.com/api/runs/1' "window_area_ne":="0" "roof_area":="900" "skylight_area":="150" "building_height":="15" "window_area_nw":="0" "window_area_se":="0" "window_area_sw":="0" "si_units":="true" "floor_area":="900" "wall_area_sw":="0" "wall_area_nw":="0" "wall_area_ne":="0" "wall_area_se":="0" "window_area_e":="200" "wall_area_w":="450" "wall_area_s":="450" "window_area_n":="200" "wall_area_n":="450" "window_area_s":="200" "window_area_w":="200" "wall_area_e":="450" "Authorization: Token aaaa1111aaaa1111aaaa1111aaaa1111aaaa"

response

{
    "data": {
        "eui_breakdown": {
            "headers": [
                "Cooling",
                "Heating",
                "Lighting",
                "Equipment",
                "Fans",
                "Pumps",
                "Hot Water"
            ],
            "values": [
                42.69810373890001,
                215.9911661803,
                35.150749997999995,
                26.540714283,
                83.00345598700001,
                4.380000116000001,
                5.9237200512
            ]
        },
        "eui_total": 413.68791035439995
    },
    "result": "success"
}

Python Example

import json, requests

class ApiHelpers:
    # Same credentials you use to log in to cove.tool
    def __init__(self, username, password):
        self.token = self._get_api_token(username, password)

    def post_request(self, path, data, use_token=True):
        url = self._api_url(path)
        headers = self._headers(use_token)
        response = requests.post(url, headers=headers, data=data)
        return self._handle_response(response)

    def get_request(self, path, use_token=True):
        url = self._api_url(path)
        headers = self._headers(use_token)
        response = requests.get(url, headers=headers)
        return self._handle_response(response)

    def _api_url(self, path):
        return 'https://app.covetool.com/api/' + path + '/'

    def _get_api_token(self, username, password):
        data = {
            'username': username,
            'password': password,
        }
        response_data = self.post_request('get-token', data, False)
        token = response_data['token']
        return str(token)

    def _headers(self, use_token):
        headers = {}
        if use_token:
            headers['Authorization'] = 'Token ' + self.token
        return headers

    def _handle_response(self, response):
        if response.ok:
            return response.json()
        else:
            return {'result': 'error'}

# Set up helpers instance
username = 'username'
password = 'password'
helpers = ApiHelpers(username, password)

# Get a list of projects
project_list = helpers.get_request('projects')
names = []
values = []
for project in project_list:
    if project['run_set']:
        name = str(project['name'])
        value = str(project['run_set'][0])
        names.append(name)
        values.append(value)

# Update a run
run = 'https://app.covetool.com/api/runs/1/'
si_units = 'true'
building_height = 15
roof_area = 900
floor_area = 900
skylight_area = 150
wall_area_e = 450
wall_area_ne = 0
wall_area_n = 450
wall_area_nw = 0
wall_area_w = 450
wall_area_sw = 0
wall_area_s = 450
wall_area_se = 0
window_area_e = 200
window_area_ne = 0
window_area_n = 200
window_area_nw = 0
window_area_w = 200
window_area_sw = 0
window_area_s = 200
window_area_se = 0

data = {
    'run': run,
    'si_units': si_units,
    'building_height': building_height,
    'roof_area': roof_area,
    'floor_area': floor_area,
    'skylight_area': skylight_area,
    'wall_area_e': wall_area_e,
    'wall_area_ne': wall_area_ne,
    'wall_area_n': wall_area_n,
    'wall_area_nw': wall_area_nw,
    'wall_area_w': wall_area_w,
    'wall_area_sw': wall_area_sw,
    'wall_area_s': wall_area_s,
    'wall_area_se': wall_area_se,
    'window_area_e': window_area_e,
    'window_area_ne': window_area_ne,
    'window_area_n': window_area_n,
    'window_area_nw': window_area_nw,
    'window_area_w': window_area_w,
    'window_area_sw': window_area_sw,
    'window_area_s': window_area_s,
    'window_area_se': window_area_se,
}

result = helpers.post_request('run-values', data)
eui_total = result['data']['eui_total']
print 'EUI Total:', eui_total
cooling = 0
heating = 0
lighting = 0
equipment = 0
fans = 0
pumps = 0
hot_water = 0
eui_breakdown = result['data']['eui_breakdown']
headers = eui_breakdown['headers']
values = eui_breakdown['values']
for i, header in enumerate(headers):
  if header == 'Cooling':
      cooling = float(values[i])
      print 'Cooling:', cooling
  elif header == 'Heating':
      heating = float(values[i])
      print 'Heating:', heating
  elif header == 'Lighting':
      lighting = float(values[i])
      print 'Lighting:', lighting
  elif header == 'Equipment':
      equipment = float(values[i])
      print 'Equipment:', equipment
  elif header == 'Fans':
      fans = float(values[i])
      print 'Fans:', fans
  elif header == 'Pumps':
      pumps = float(values[i])
      print 'Pumps:', pumps
  elif header == 'Hot Water':
      hot_water = float(values[i])
      print 'Hot Water:', hot_water

Did this answer your question?