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).
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.
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.
#
/hc/theming_assets/01KQ5XBDYYTXVM27HQYH0SY956
FAQ
Questions about the platform and services
custom
#
/hc/theming_assets/01KQ5XBE98VXY0Y96SYWBEG7CG
Guides
Instructions related to interacting with different online features
community
/hc/en-us/community/topics
/hc/theming_assets/01KQ5XBEKHR3CYXAJZ194NV4D9
Community
Join a community of organizations looking to go net-zero