Glimpse Calculator Technical Methodology: API

Developer Information

The Virtual Energy Efficiency Team maintains a robust and up-to-date API documentation on ReadMe. This page is only accessible to API Members (Become an API member today).

Become an API member today

The ReadMe Includes:

Testing Capabilities & Examples

Testing Capabilities: Use the documentation like a UI to construct and send test requests to each API endpoint. Valid ranges and values are given to make sure your tests remain valid. Testing capabilities have multiple programming languages to choose from.
Examples: See the real world examples we’ve constructed to demonstrate the full usage of each endpoint.

Input & Output Structure

All inputs and the output structure of each service endpoint. For numerical inputs, it details the valid ranges. For string inputs, it details the valid options.
Descriptions for how to use each input option.

The building calculations services create energy models of the baseline and EIM scenarios, simulate them, and process them. In some cases, the models have been pre-simulated, allowing the response time to be greatly reduced. The outputs of the building calculations always include the annual energy usage, utility cost, and emissions of the baseline scenario and the savings of all three metrics for each of the simulated EIMs.

Detailed Building Calculations (Tier 2)

The detailed API is a way of accessing on-demand building energy models. Inputs allowed include ways to specify the energy-relevant attributes of roofs, walls, windows, skylights, lighting systems, HVAC systems, hot water systems, elevators, and operations characteristics of a building. Additional inputs include the basic (Tier 1) inputs to allow the Glimpse Calculator to make assumptions for values not given. If utilizing the “Calibration” feature, the user must also pass monthly energy usage per fuel type used in the building for each month in a representative year.

Main Tier 2 API Inputs:

Building general information

Parameter	Description
`site_id`	ID client uses for the building
`site_name`	Name client uses for the building
`year_built`	Building construction year
`square_footage`	Gross floor area in ft²
`zip_code`	5-digit ZIP/postal code
`usetypes[].type`	Building function or use type
`usetypes[].pct_area`	Percent of building area associated with this use type

Elevators

Parameter	Description
`elevators[].type`	Elevator type
`elevators[].quantity`	Count of elevators
`elevators[].year`	Elevator installation year

Lighting

Parameter	Description
`lights[].lamp_watts`	Per-fixture lamp wattage
`lights[].lamps_per_fixture`	Number of lamps per fixture
`lights[].quantity`	Fixture count

Building HVAC Metadata

Parameter	Description
`perc_building_loops`	Percent of building load served by plant loops
`perc_building_ahus`	Percent of building load served by air handlers
`perc_building_zoneeqp`	Percent of building load served by zone equipment
`perc_building_vrf`	Percent of building load served by VRF systems

Air Handlers Units

Parameter	Description
`air_handlers[].system_type`	System type
`air_handlers[].cooling_source`	Cooling source
`air_handlers[].heating_source`	Heating source
`air_handlers[].furnace_fuel`	Furnace fuel type
`air_handlers[].distribution_type`	Distribution type
`air_handlers[].terminalunit_type`	Terminal unit type
`air_handlers[].terminalunit_reheat`	Terminal unit reheat energy source
`air_handlers[].cooling_cop`	Air-handler cooling COP
`air_handlers[].furnace_efficiency`	Furnace efficiency (fraction)
`air_handlers[].heatpump_heating_cop`	Air-handler heat pump heating COP
`air_handlers[].total_fan_hp`	Total supply/return fan horsepower
`air_handlers[].total_fan_efficiency`	Combined fan efficiency (fraction)
`air_handlers[].total_fan_cfm`	Total fan airflow in CFM
`air_handlers[].economizer`	Flag indicating presence of an economizer
`air_handlers[].heat_recovery`	Flag indicating presence of heat recovery
`air_handlers[].fans_variable_speed`	Flag indicating variable speed fans
`air_handlers[].perc_served`	Percent of building load served by this air handler

Central Plant Units

Parameter	Description
`loops[].heating_source`	Plant heating source
`loops[].cooling_source`	Plant cooling source
`loops[].boiler_fuel`	Boiler fuel type
`loops[].pump_power_w_per_gpm`	Pump power intensity in W/gpm
`loops[].chiller_cop`	Chiller COP
`loops[].boiler_efficiency`	Boiler efficiency (fraction)
`loops[].heatpump_heating_cop`	Heat pump heating COP
`loops[].heatpump_cooling_cop`	Heat pump cooling COP
`loops[].condenser_fan_combined_horsepower`	Combined condenser fan horsepower
`loops[].pumps_variable_speed`	Flag
`loops[].perc_served`	Float between 0 and 100 inclusive (Range(0, 100)), allow_none=True

Single Zone Units

Parameter	Description
`single_zone_units[].heating_type`	Single-zone unit heating type
`single_zone_units[].heating_cop`	Heating COP for heat pump systems
`single_zone_units[].heating_efficiency`	Heating efficiency for combustion systems
`single_zone_units[].cooling_cop`	Cooling COP
`single_zone_units[].outdoor_air`	Flag indicating provision of outdoor air
`single_zone_units[].heat_recovery`	Flag indicating presence of heat recovery
`single_zone_units[].fan_variable_speed`	Flag indicating variable speed fans
`single_zone_units[].perc_served`	Percent of building served by single-zone units

Variable Refrigerant Flow Units

Parameter	Description
`vrf_units[].cool_cop`	VRF cooling COP
`vrf_units[].heat_cop`	VRF heating COP
`vrf_units[].perc_served`	Percent of building served by this VRF unit

Zone Heater Units

Parameter	Description
`zone_heaters[].fuel`	Zone heater fuel type
`zone_heaters[].efficiency`	Zone heater efficiency (fraction)
`zone_heaters[].perc_served`	Percent of building served by zone heaters

Exhaust Fans

Parameter	Description
`exhaust_fans[].horsepower`	Exhaust fan motor horsepower
`exhaust_fans[].cfm`	Exhaust airflow in cfm
`exhaust_fans[].schedule`	Exhaust fan schedule

Roofs

Parameter	Description
`roofs[].type`	Per-roof field
`roofs[].area`	Per-roof area in ft²
`roofs[].uval`	Per-roof U-value (Btu/hr·ft²·°F)
`roofs[].rval`	Per-roof R-value (hr·ft²·°F/Btu)
`roofs[].insulation_thickness_inches`	Roof insulation thickness in inches
`roofs[].cool_bool`	Per-roof flag indicating cool roof

Skylights

Parameter	Description
`skylights[].type`	Per-skylight field
`skylights[].area`	Per-skylight area in ft²
`skylights[].uval`	Per-skylight U-value
`skylights[].shgc`	Per heat gain coefficient (SHGC)
`skylights[].vt`	visible transmittance (VT)

Walls

Parameter	Description
`walls[].type`	Per-wall construction type
`walls[].area`	Per-wall area in ft²
`walls[].uval`	Per-wall U-value
`walls[].rval`	Per-wall R-value
`walls[].insulation_thickness_inches`	Wall insulation thickness in inches

Windows

Parameter	Description
`windows[].area`	Per-window area in ft²
`windows[].uval`	Per-window U-value
`windows[].shgc`	Per-window SHGC
`windows[].vt`	Per-window VT

Water Heaters

Parameter	Description
`water_heaters[].fuel`	Water heater fuel type
`water_heaters[].style`	Water heater style
`water_heaters[].efficiency`	Water heater efficiency (fraction)
`water_heaters[].insul_thickness_in`	Tank insulation thickness in inches
`water_heaters[].insul_thickness_rval`	Tank insulation R-value
`water_heaters[].perc_served`	Percent of domestic hot water load served

Usage Data

Parameter	Description
`measured_usage`	Dict of measured monthly usage by fuel
`history_years`	List of historical years
`history_annual_kbtu_by_fuel`	List of annual usage dictionaries by fuel per year
`past_renovation_years`	List of past renovation years

Operations

Parameter	Description
`operations[].misc_epd_w_ft2`	Miscellaneous plug/process load EPD in W/ft²
`operations[].misc_gpd_w_ft2`	Miscellaneous water use in gal/day/ft²
`operations[].occupants`	Occupant count
`operations[].spt_heating_f`	Setpoint for heating operations (°F)
`operations[].spt_cooling_f`	Setpoint for cooling systems (°F)
`operations[].wkdy_start_hr`	Schedule hour (0-24)
`operations[].wkdy_end_hr`	Schedule hour (0-24)
`operations[].sat_start_hr`	Schedule hour (0-24)
`operations[].sat_end_hr`	Schedule hour (0-24)
`operations[].sun_start_hr`	Schedule hour (0-24)
`operations[].sun_end_hr`	Schedule hour (0-24)

Simple Building Calculations (Tier 1)

The simple API offers the same options as the detailed building API but for use cases when only a minimal amount of information is known about a building. In these cases, five building attributes can (and must) be specified (listed below), and the same outputs are available. This method of accessing the Glimpse Calculator speeds up response time because a model for each possible combination of the five parameters has been pre-simulated, taking the energy model simulation time out of the equation.

The required Tier 1 attributes are:
1. Building type	4. Primary heating fuel
2. Zip code	5. Floor area (square feet)
3. Year of construction or last renovation

Building Calculations Outputs

When using either the simple or the detailed input method to interact with the Glimpse API building calculations, the same outputs are returned.

Baseline Outputs

Annual energy usage (in kWh)
- Broken down by end-uses - interior lights, exterior lights, interior equipment, fans, pumps, heating, cooling, humidification, water systems, exterior equipment
- Broken down by fuels (as they enter the building) -
  
  Electricity
  
  Natural gas
  
  Fuel oil
  
  District heat (steam)
  
  District heat (hot water)
  
  Coal
  
  Propane
- Optionally, the monthly distribution of each of these annual energy usage numbers
Annual energy utility cost (in USD)
Annual scope 1 and 2 emissions (in lbs of CO2e)

EIM List

EIM Impact and Savings

Annual energy savings
Annual energy utility cost savings
Annual scope 1 and 2 emissions reduction

Optional Outputs

Optionally, if the feature is contracted for, an API user can elect to receive the following outputs:

Life-cycle cost and impact analysis: This includes financial metrics like useful life, lifetime energy savings, cost savings, emissions reduction, and total metrics like NPV and IRR for all EIMs.
Building performance standards: This includes information on any applicable state or municipal policies that require reduction of building energy consumption or associated emissions. It includes the fines, targets, and dates associated with these policies, compliance routes to abide by the policies, and the generation of strategies to avoid any non-compliance penalties, if applicable.

VEE API