Request Structure

The following sections provide the specifications and syntax for each API request schema.

Top-level request payload schema

{
  "addressFull": "197 RANDALL RD, BALLSTON SPA, NY 12020",
  "addressComponents": ADDRESS_COMPONENTS,
  "baseBuilding": BASE_BUILDING,
  "globalControls": GLOBAL_CONTROLS, 
  "defaultModelControls": MODEL_CONTROLS,
  "timelines": [ TIMELINE ]
}

As discussed in Usage Instructions, the Defaulting Engine will populate any missing or null building characteristics. In each schema definition table below, information about each key’s default is provided.

• PSC: Property-specific characteristic. This type of default indicates that specific information about the address is collected and applied to that attribute. Thus, each address may have a different default value. For example, buildingSummary.conditionedFloorArea is collected from various Data Sources to be populated when missing or null.

• BSA : Building stock assumption. This type of default indicates that location- and vintage-based building stock assumptions are used by the defaulting engine to populate missing and null keys.

Note

Objects and arrays are used as values throughout the API. The difference is:

• Object: This represents a single item that is not inherently a collection. An example of this is Air Infiltration, which is characteristic of the entire building and thus can only be defined once.

• Array: This represents an item that is inherently a collection, even if we don’t yet support more than one item. Often it will be an array of objects, where each object defines an item in the collection. HVAC and Walls are examples of this.

Address

An address can be specified using either addressFull or addressComponents.

Address Full

{
  "addressFull": "197 RANDALL RD, BALLSTON SPA, NY 12020"
}

Address Components

{
  "addressLine1": "197 Randall Road",
  "addressLine2": "Unit A",
  "city": "Ballston Spa",
  "stateAbbreviation": "NY",
  "zipCode": "12020"
}

Base Building

{
  "buildingSummary": {
    "conditionedFloorArea": 2413,
    "averageCeilingHeight": 8,
    "bathCount": 2,
    "bedroomsCount": 4,
    "residentCount": 2,
    "storiesCount": 2,
    "windowToWallFraction": 0.14,
    "yearBuilt": 1999,
    "propertyUse": "single-family detached"
  },
  "enclosure": ENCLOSURE,
  "systems": {
    "hvac": HVAC,
    "waterHeating": WATER_HEATING,
    "electricalPanels": [ ELECTRICAL_PANEL ],
    "photovoltaics": [ PHOTOVOLTAIC ],
  },
  "appliances": APPLIANCES
}

Building Summary

Property	Type	Units	Constraints	Required	Default	Notes
conditionedFloorArea	integer	ft2	>0	no	PSC	If missing from PSC, model will fail
averageCeilingHeight	integer	ft	>0	no	8
bathCount	integer	count	>0	no	see [1]
bedroomsCount	integer	count	>0	no	PSC, BSA
residentCount	integer	count	>=0	no	BSA
storiesCount	integer	count	>0	no	PSC, BSA
windowToWallFraction	float	fraction	>0	no	0.14
yearBuilt	integer	year	>1600	no	PSC	If missing from PSC, model will fail
propertyUse	string		see [2]	no	PSC	Advanced option. See [3]

[1]

bedroomsCount/2 + 0.5

[2]

propertyUse options are “single-family detached”, “single-family attached”, or “manufactured home”.

[3]

propertyUse is an advanced field. Overriding the existing property use may produce in abnormal model results. If you set this, we recommend setting conditionedFloorArea as well.

Enclosure

//ENCLOSURE
{
  "airInfiltration": {
    "rate": 15.0,
    "rateUnit": "ACH", // if null, default is ACH
    "housePressurePa": 50.0, // if null, default is 50 Pa
  },

  "attics": [ // required to be 1
    {
      "id": "Attic1",
      "type": "attic vented", // ("attic vented" | "attic unvented" | "cathedral ceiling" | "flat roof")
      "area": 1225,
      "floorAssemblyEffectiveRValue": 20.6
    }
  ],

  "roofs": [ // limited to 1
    {
      "id": "Roof1",
      "area": 1370,
      "pitch": 6,
      "assemblyEffectiveRValue": 2.3,
      "lifetime": LIFETIME // optional, refer to Lifetime schema
    }
  ],

  "foundations": [ // limited to 1
    {
      "id": "BasementUnconditioned1",
      "type": "basement unconditioned", // ("basement conditioned" | "basement unconditioned" | "crawl vented" | "crawl unvented" | "slab" | "belly any wing")
      "area": 1234, // if the area is less than the footprint area, the remainder will be assigned to crawlspace
      "wallHeight": 8,
    }
  ],

  "walls": [ // limited to 1
    {
      "id": "Wall1",
      "type": "wood stud", // ("wood stud" | "concrete masonry unit" | "structural brick" | "steel frame" | "stone" | "adobe" | "log wall" | "solid concrete")
      "area": 1234,
      "assemblyEffectiveRValue": 10.9,
      "fractionAreaShared": 0.0, // fraction of wall area shared with an adjacent structure or dwelling unit (e.g. townhouses)
    }
  ],
}

Air Infiltration

Property	Type	Units	Constraints	Required	Default	Notes
rate	float	see rateUnit	>0	no	BSA
rateUnit	string		see [4]	no	ACH
housePressurePa	float	Pascals	>0	no	50

[4]

rateUnit options are “ACH” or “CFM”

Attics

The attic is entered in ...building.enclosure.attics. Currently, this array must contain exactly 1 attic object. If there is no attic present in house, set area to 0. See note about objects and arrays for more information.

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	Attic1
area	float	ft2	>0	no	PSC
isVented	boolean			no	yes
floorAssemblyEffectiveRValue	float	F-ft2-hr/Btu	>0	no	BSA

Roofs

Each roof surface is entered in ...building.enclosure.roofs. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	Roof1
area	float	ft2	>0	no	PSC
pitch	float	?:12	>=0	no	6
assemblyEffectiveRValue	float	F-ft2-hr/Btu	>0	no	2.3

Foundations

Each foundation is entered in ...building.enclosure.foundations. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

Property	Type	Units	Constraints	Required	Default	Notes
id	id		must be unique	yes	PSC
type	string		see [5]	no	BSA
area	float	ft2	>0	no	PSC
wallHeight	float	ft	>=0	no	PSC

[5]

type choices are “basement conditioned”, “basement unconditioned”, “crawl vented”, “crawl unvented”, “slab”, and “pier and beam”.

Walls

Each wall that has no contact with the ground and bounds a space is entered in ...building.enclosure.walls. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	Wall1
type	string		see [6]	no	BSA
assemblyEffectiveRValue	float	F-ft2-hr/Btu	>0	no	BSA
fractionAreaShared	float	fraction	0-1	no	PSC
area	float	ft2	>0	no	PSC

[6]

type choices are “wood stud”, “concrete masonry unit”, “structural brick”, “steel frame”, “stone”, “adobe”, “log wall”, and “solid concrete”.

HVAC

Each HVAC system can be entered in ...building.systems.hvac.

{
  "hvacCoolingSystems": [ HVAC_COOLING_SYSTEM ],
  "hvacHeatingSystems": [ HVAC_HEATING_SYSTEM ],
  "hvacHeatPumps": [ HVAC_HEAT_PUMP ],
  "hvacDistributionSystems": {
    "airDistributionSystems": [ AIR_DISTRIBUTION_SYSTEM ],
    "hydronicDistributionSystems": [ HYDRONIC_DISTRIBUTION_SYSTEM ]
  },
  "hvacControlSystems": [ HVAC_CONTROL_SYSTEM ],
  "coolLoadGapFraction": 0.2,
  "heatLoadGapFraction": 0.0
}

HVAC Cooling Systems

Each space cooling system (other than a heat pump) can be entered in ...building.systems.hvac.hvacCoolingSystems. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

{
  "id": "CentralAirConditioner1",
  "connectedDistributionId": "HVACDistributionFurnaceAndCentralAC1",
  "systemType": "central air conditioner",
  "coolCapacityBtuPerHour": 1000.0,
  "compressorType": "single stage",
  "coolEfficiency": 12,
  "coolEfficiencyUnits": "SEER",
  "coolLoadFraction": 0.8,
  "lifetime": LIFETIME
}

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	PSC
connectedDistributionId	idref			yes [7]	PSC
systemType	string		see [8]	yes	PSC, BSA
coolCapacityBtuPerHour	float	Btu/hr	>=0	no		autosized by modeling engine if undefined
compressorType	string		see [9]	no	single stage	only applicable if systemType = “central air conditioner”
coolEfficiency	float	see coolEfficiencyUnits	>0	no	PSC
coolEfficiencyUnits	string		see [10]	no	PSC
coolLoadFraction	float	fraction	<=1	yes	1

[7]

If systemType is “central air conditioner”

[8]

systemType choices are “central air conditioner”, “room air conditioner”, “evaporative cooler”, “packaged terminal air conditioner”, and “mini-split”.

[9]

compressorType choices are “single stage”, “two stage”, and “variable speed”.

[10]

coolEfficiencyUnits choices “EER” and “CEER” for room air conditioners and packaged terminal air conditioners. “SEER” and “SEER2” are the choices for central air conditioners and mini-splits. Evaporative coolers do not require coolEfficiency.

HVAC Heating Systems

Each space heating system (other than a heat pump) can be entered in ...building.systems.hvac.hvacHeatingSystems. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

{
  "id": "Boiler1",
  "connectedDistributionId": "HVACHydronicDistribtuionSystem1",
  "systemType": "boiler",
  "fuel": "natural gas",
  "heatCapacityBtuPerHour": 1000.0,
  "heatEfficiency": 0.8,
  "heatEfficiencyUnits": "AFUE",
  "heatLoadFraction": 0.8,
  "lifetime": LIFETIME
}

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	PSC
connectedDistributionId	idref			see [11]	PSC
systemType	string		see [12]	yes	PSC, BSA
fuel	string		see [13]	no	PSC
heatCapacityBtuPerHour	float	Btu/hr	>=0	no		autosized by modeling engine if undefined
heatEfficiency	float	see heatEfficiencyUnits	0-1	no	PSC
heatEfficiencyUnits	string		see [14]	no	PSC
heatLoadFraction	float	fraction	0-1	yes	1

[11]

Required when systemType is “furnace” or “boiler”.

[12]

systemType choices are “electric resistance”, “furnace”, “wall furnace”, “boiler”, “stove”, “portable heater”, “fixed heater”, and “fireplace”.

[13]

fuel choices are “electricity”, “natural gas”, “fuel oil”, “propane”, “coal”, “wood”, and “wood pellets”.

[14]

heatEfficiencyUnits choices are “AFUE” and “fraction”.

HVAC Heat Pumps

Each space conditioning heat pump can be entered in ...building.systems.hvac.hvacHeatPumps. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

{
  "id": "ASHP1",
  "connectedDistributionId": "HVACDistributionASHP1",
  "systemType": "air-to-air",
  "compressorType": "variable speed",
  "backupSystem": {
    "systemType": "integrated",
    "heatingSwitchoverTemp": 10,
    "fuel": "natural gas",
    "heatEfficiency": 0.8,
    "heatEfficiencyUnits": "AFUE",
    "heatCapacityBtuPerHour": 2000,
    "backupHvacId": "Boiler1",
  },
  "heatCapacityBtuPerHour": 1000.0,
  "coolCapacityBtuPerHour": 1000.0,
  "heatEfficiency": 10,
  "heatEfficiencyUnits": "HSPF",
  "coolEfficiency": 19,
  "coolEfficiencyUnits": "SEER",
  "heatLoadFraction": 0.8,
  "coolLoadFraction": 0.8,
  "lifetime": LIFETIME
}

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	PSC
connectedDistributionId	idref		see [15]	see [16]	PSC
systemType	string		see [17]	yes	PSC
compressorType	string		see [18]	no	single stage
heatCapacityBtuPerHour	float	Btu/hr	>=0	no		autosized by modeling engine if undefined
coolCapacityBtuPerHour	float	Btu/hr	>=0	no		autosized by modeling engine if undefined
heatEfficiency	float	Btu/Wh	>0	no	PSC
heatEfficiencyUnits	string		see [19]	no	HSPF
coolEfficiency	float	Btu/Wh	>0	no	PSC
coolEfficiencyUnits	string		see [21]	no	SEER
heatLoadFraction	float	fraction	0-1	yes	1
coolLoadFraction	float	fraction	0-1	yes	1
backupSystem	object			yes

[15]

Must reference a defined hvacDistributionSystem.id.

[16]

Required when systemType is “air-to-air” or “ground-to-air”.

[17]

systemType choices are “mini-split”, “air-to-air”, and “ground-to-air”.

[18]

compressorType choices are “single stage”, “two stage”, and “variable speed”.

[19]

heatEfficiencyUnits choices are “HSPF” or “HSPF2”.

[21]

coolEfficiencyUnits choices are “SEER” or “SEER2”.

backupSystem schema for HVAC Heat Pumps:

Property	Type	Units	Constraints	Required	Default	Notes
systemType	string		see [22]	no	integrated
heatingSwitchoverTemp	float	F		no		determined by modeling engine if undefined
fuel	string		see [23]	no	electricity	only applicable if backupSystem.systemType = “integrated”
heatEfficiency	float	see heatEfficiencyUnit	0-1	no	1	only applicable if backupSystem.systemType = “integrated”
heatEfficiencyUnits	string		see [24]	no	fraction	only applicable if backupSystem.systemType = “integrated”
heatCapacityBtuPerHour	float	Btu/hr	>=0	no		autosized by modeling engine if undefined, only applicable if backupSystem.systemType = “integrated”
backupHvacId	idref		see [25]	see [26]	PSC

[22]

systemType choices are “integrated” and “separate”.

[23]

fuel choices are “electricity”, “natural gas”, “fuel oil”, “propane”, “coal”, “wood”, and “wood pellets”.

[24]

heatEfficiencyUnits choices are “AFUE” and “fraction”.

[25]

Must reference an defined hvacHeatingSystem.id

[26]

Required when backupSystem.systemType is “separate”.

Air Distribution Systems

Each separate air distribution system can be entered in ...building.systems.hvac.hvacDistributionSystems.airDistributionSystems. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

{
  "id": "HVACDistributionFurnaceAndCentralAC1",
  "systemType": "regular velocity",
  "numberOfReturnRegisters": 2,
  "conditionedFloorAreaServed": 3456,
  "ducts": {
    "supply": [
      {
        "id": "HVACDistributionFurnaceAndCentral1Supply",
        "insulationRValue": 0.0,
        "leakageValue": 0.2,
        "leakageUnits": "fraction",
        "location": "attic vented"
      }
    ],
    "return": [
      {
        "id": "HVACDistributionFurnaceAndCentral1Return",
        "insulationRValue": 0.0,
        "leakageValue": 0.2,
        "leakageUnits": "fraction",
        "location": "attic vented"
      }
    ]
  }
}

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	PSC
systemType	string		see [27]	yes	PSC
numberOfReturnRegisters	integer	count	>=0	no	PSC
conditionedFloorAreaServed	float	ft2	>0	no	PSC
ducts	object			yes

[27]

systemType choices are “regular velocity” and “gravity”.

ducts contains two keys, supply and return. Each of these keys are object arrays using the following schema:

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	PSC
insulationRValue	float	F-ft2-hr/Btu	>=0	no	0
leakageValue	float	see leakageUnits	>=0	no	BSA
leakageUnits	string		see [28]	no	fraction
location	string		see [29]	no	see notes [30]

[28]

leakageUnits choices are “CFM25”, “CFM50”, and “fraction”.

[29]

location choices are “living space”, “basement conditioned”, “basement unconditioned”, “crawlspace unvented”, “crawlspace vented”, “attic unvented”, “attic vented”, “garage”, “outside”, “exterior wall”, “under slab”, “roof deck”, “other heated space”, and “other non-freezing space”.

[30]

If location not provided, defaults to the first present space type: “basement conditioned”, “basement unconditioned”, “crawlspace vented”, “crawlspace unvented”, “attic vented”, “attic unvented”, “garage”, or “living space”.

Hydronic Distribution Systems

Each separate hydronic distribution system can be entered in ...building.systems.hvac.hvacDistributionSystems.hydronicDistributionSystems. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

{
  "id": "HVACDistributionBoiler1",
  "systemType": "baseboard",
  "conditionedFloorAreaServed": 3456
}

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	PSC
systemType	string			yes
conditionedFloorAreaServed	float	ft2	>0	no	PSC

HVAC Control Systems

If any HVAC systems are specified, a single control system can be entered in ...building.systems.hvac.hvacControlSystems.

{
  "id": "HVACControl1",
  "heatingSeason": {
    "setpointTemp": 68,
    "setbackTemp": null,
    "setbackStartHour": null,
    "totalWeeklySetbackHours": null,
  },
  "coolingSeason": {
    "setpointTemp": 78,
    "setbackTemp": null,
    "setbackStartHour": null,
    "totalWeeklySetbackHours": null,
  },
  "lifetime": LIFETIME
}

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	HVACControl1
heatingSeason	object					Thermostat settings for heating season
coolingSeason	object					Thermostat settings for cooling season

heatingSeason and coolingSeason objects share the following schema:

Property	Type	Units	Constraints	Required	Default	Notes
setpointTemp	float	F		no	Heating: 67, Cooling: 78
setbackTemp	float	F		no	null	Also referred to as setup temperature for the cooling season.
setbackStartHour	integer	time	0-23	no	null
totalWeeklySetbackHours	integer	hrs/week	0-168	no	null

Water Heating Systems

Each water heater is entered in ...building.systems.waterHeatingSystems. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

{
  "waterHeatingSystems": [
    {
      "id": "WaterHeater1",
      "systemType": "storage water heater",
      "connectedHeatingId": "Boiler1",
      "fuel": "natural gas",
      "location": "living space",
      "tankVolume": 40,
      "dhwLoadFraction": 1.0,
      "heatCapacityBtuPerHour": null,
      "efficiency": 0.92,
      "efficiencyUnits": "EF",
      "hotWaterTemperature": 125.0,
      "performanceAdjustment": null,
      "lifetime": LIFETIME
    }
  ]
}

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	WaterHeater1
systemType	string		see [31]	yes	storage water heater
connectedHeatingId	idref		see [32]	see [33]	null
fuel	string		see [34]	no
location	string		see [35]	no	see [36]
tankVolume	float	gal		no
dhwLoadFraction	float	fraction	0-1	yes		sum of dhwLoadFraction must equal 1
heatCapacityBtuPerHour	float	Btu/hr	>0	no		autosized by modeling engine if undefined
efficency	float	fraction	>0	no	BSA
efficiencyUnits	string		see [37]	no	BSA
hotWaterTemperature	float	F	>0	no	125
performanceAdjustment	float	fraction	0-1, see [38]	no	see [39]	Multiplier on efficiency, typically to account for cycling

[31]

systemType choices are “storage water heater”, “instantaneous water heater”, “heat pump water heater”, “space-heating boiler with storage tank”, and “space-heating boiler with tankless coil”.

[32]

Must reference a defined hvacHeatingSystem.id.

[33]

Only required when systemType is “space-heating boiler with …”

[34]

fuel choices are “electricity”, “natural gas”, “fuel oil”, “propane”, “coal”, “wood”, and “wood pellets”.

[35]

location choices are “living space”, “basement conditioned”, “basement unconditioned”, “crawlspace unvented”, “crawlspace vented”, “attic unvented”, “attic vented”, “garage”, “other exterior”, “other heated space”, and “other non-freezing space”.

[36]

If location not provided, defaults to the first present space type:

IECC zones 1-3, excluding 3A: “garage”, “living space”

IECC zones 3A, 4-8, unknown: “basement conditioned”, “basement unconditioned”, “living space”

[37]

efficiencyUnits choices are “EF” and “UEF”.

[38]

Only applicable when systemType is “instantaneous water heater”

[39]

performanceAdjustment defaults to 0.94 (UEF) or 0.92 (EF)

Electrical Panels

Each electrical panel is entered in ...building.systems.electricalPanels. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

{
  "id": "ElectricPanel1",
  "lifetime": LIFETIME
}

Photovoltaics

Each solar electric photovoltaic (PV) system is entered in ...building.systems.photovoltaics. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

{
  "id": "PV1",
  "location": "roof",
  "moduleType": "standard",
  "tracking": "fixed",
  "arrayOrientation": "south",
  "arrayTilt": 45,
  "maxPowerOutput": 1000,
  "inverterEfficiency": 0.96,
  "yearModulesManufactured": 2022
}

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	not defined
location	string		see [40]	no	“roof”
moduleType	string		see [41]	no	“standard”
tracking	string		see [42]	no	“fixed”
arrayOrientation	string	direction	see [43]	yes
arrayTilt	float	degrees	0-90	yes		Tilt relative to horizontal
maxPowerOutput	float	W	>0	yes
inverterEfficiency	float	fraction	0-1	no	0.96
yearModulesManufactured	integer	year	>1600	no		Informs systemLossesFraction, which defaults to 0.14

[40]

location choices are “ground” and “roof”.

[41]

moduleType choices are “standard”, “premium”, and “thin film”.

[42]

tracking choices are “fixed”, “1-axis”, “1-axis backtracked”, and “2-axis”.

[43]

arrayOrientation choices are “northeast”, “east”, “southeast”, “south”, “southwest”, “west”, “northwest”, and “north”.

Appliances

Appliances can be entered in ...building.appliances.

{
  "clothesDryers": [ CLOTHES_DRYER ],
  "cookingRanges": [ COOKING_RANGE ]
}

Clothes Dryers

Clothes dryers can be entered in ...building.appliances.clothesDryers. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

{
  "id": "ClothesDryer1",
  "fuel": "electricity",
  "combinedEnergyFactor": 3.73,
  "isVented": true,
  "ventedFlowRate": 150,
  "lifetime": LIFETIME
}

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	ClothesDryer1
fuel	string		see [44]	no	BSA
combinedEnergyFactor	float	lb/kWh	>0	no	3.73
isVented	boolean			no	true
ventedFlowRate	float	ft3/min		no	150

[44]

fuel choices are “electricity”, “natural gas”, “fuel oil”, “propane”, “coal”, “wood”, and “wood pellets”.

Cooking Ranges

Cooking ranges can be entered in ...building.appliances.cookingRanges. Currently, this array is limited to a maximum size of 1. See note about objects and arrays for more information.

{
  "id": "CookingRange1",
  "fuel": "electricity",
  "isInduction": false,
  "lifetime": LIFETIME
}

Property	Type	Units	Constraints	Required	Default	Notes
id	id		Must be unique	yes	CookingRange1
fuel	string		see [45]	no	PSC, BSA
isInduction	boolean			no	false

[45]

fuel choices are “electricity”, “natural gas”, “fuel oil”, “propane”, “coal”, “wood”, and “wood pellets”.

Lifetime

//LIFETIME
{
  "replacementCost": 1000, // required if status quo timeline requested. cost to replace system with a near-equivalent that is available today

  // Two of the following three properties can be optionally defined to place an existing system on the status quo timeline.
  // Default values are based on system type and year built.
  "effectiveUsefulLifeDays": 5475,
  "installedDate": "2018-01-01",
  "endOfLifeDate": "2032-12-31"
}

Property	Type	Units	Constraints	Required	Default	Notes
replacementCost	float	units.monetary	>=0	see [46]		Default values not supported currently
endOfLifeDate	date		in the future	see [47]
effectiveUsefulLifeDays	integer	days	>0	see [47]	BSA
installedDate	date		in the past	see [47]	PSC, BSA

[46]

Required to run status quo timeline.

[47] (1,2,3)

Two of these three properties (endOfLifeDate, effectiveUsefulLifeDays, installedDate) are required to be included in the status quo timeline.

Timelines

// TIMELINE
{
  "id": "<UUID>", // optional, if missing an UUID is generated

  "label": "MY_TIMELINE", // optional, if missing an random adjective-animal string is generated

  "comparedTo": "hilarious-hyena", // optional, needs to exist in the current payload, if missing it defaults to STATUS_QUO

  "models": [ MODEL ], // refer to the Model schema
}

Models

// MODEL
{
  "id": "<UUID>", // optional, if missing an UUID is generated

  "label": "NYSERDA001", // optional, if missing an UUID is generated

  "appliedOn": "<DATE>", // date in the YYYY-MM-DD format, defaults to today's date

  "modelControls": MODEL_CONTROLS, // optional, refer to the Model Controls schema

  "loans": [ LOAN ], // optional, refer to the Loan schema

  "incentives": [ INCENTIVE ], //optional, refer to the Incentive schema

  "automatedMeasures": AUTOMATED_MEASURES, //optional, refer to the Automated Measures schema

  "customMeasures": [ CUSTOM_MEASURE ], // optional, refer to the Custom Measure schema

  "improvedBuilding": IMPROVED_BUILDING, // optional, refer to the Improved Building schema

  "userData": { // optional, user-defined labels (only strings) to associate with the model, mirrored in the response
    "myKey": "aValue",
  }
}

Model Controls

Model controls (timelines.models.modelControls) and default model controls (defaultModelControls) are optional schemas. If the default model controls object is provided, and no model controls object is present in a given model, values in this object are taken by default, affecting such model.

// MODEL_CONTROLS (mirrored at the model level)
{
  // Allows the user to control HVAC sizing behavior if HVAC capacities are defined. If capacities are undefined, the model will autosize the system.
  // If false, the user-specified fixed capacity will be used.
  // If true, the maximum of the user-specified fixed capacity and the heating/cooling
  // design load will be used to reduce potential for unmet loads.
  // If not provided, the default value is false.
  //
  "allowIncreasedFixedCapacities": false,

  // Describes how autosized heat pumps are handled.
  // If "max load", heat pumps are sized based on the maximum of heating and cooling design loads.
  // If "acca", heat pumps are sized per ACCA Manual J/S based on cooling design loads with some oversizing allowances for heating design loads.
  // If "hers", autosized heat pumps have their nominal capacity sized equal to the larger of heating/cooling design loads.
  // If not provided, the default value of "acca" is used.
  "heatPumpSizingMethodology": "acca", // ("acca" | "max load" | "hers")

  "energyCostRates": ENERGY_COST_RATES, // optional, refer to the Energy Costs Rates schema

  "weather": WEATHER, // optional, refer to Weather schema
}

Energy Costs Rates

// ENERGY_COST_RATES
// Rate units will be based on monetary unit per fuel unit, as defined in UNITS schema.
// If a rate is provided, but the unit property is not, throw an error.
// Example: units.electricity = "kWh" and units.monetary = "USD", electricity energy cost rate is USD per kWh

{
  "electricity": {
    "kwh": 0.0,
  },
  "naturalGas": {
    "ccf": 0.0,
  }
  "coal": {
    "mbtu": 0.0,
  }
}

Weather

// WEATHER
{
  "label": "some-weather-file-label",
  "type": "epw", // ("epw")
  "encoding": "base64", // ("base64")
  "data": "SGVsbG8sIFdvcmxkIQ==",
  "checksum": "addf120b430021c36c232caaef8d926aea2acd6b" // optional, in SHA256
}

Loans

// LOAN
{
  "id": "Loan1",
  "label": "USER_DEFINED_1",
  "description": "Colorado loan loss reserve",
  "termInMonths": 240,
  "interestRateAnnual": 0.07,
  "principalValue": 20000, // if null, total cost of COST schemas referencing this id
  "downPayment": 2000,
  "closingCost": 1000,
  "minLoanAmount": 2000, //optional
  "maxLoanAmount": 100000 //optional
}

Incentives

// INCENTIVE
{
  "id": "Incentive1",
  "fixedAmount": 100,
  "relativeFraction": 0.04,
  "absoluteMin": 100,
  "absoluteMax": 10000,
  "availableDate": "2023-01-01" //if null, defaults to model.appliedOn
}

Automated Measures

Automated measures allow users to apply improvements to the base building without fully defining either the base or improved building definition.

{
  "existingHvacHeatingSystem": { EXISTING_HVAC_HEATING_SYSTEM },
  "existingHvacCoolingSystem": { EXISTING_HVAC_COOLING_SYSTEM },
  "existingHvacDistributionSystem": { EXISTING_HVAC_DISTRIBUTION_SYSTEM },
  "existingWaterHeatingSystem": { EXISTING_WATER_HEATING_SYSTEM },
  "newHeatPump": { NEW_HEAT_PUMP },
  "newWaterHeatingSystem": { NEW_WATER_HEATING_SYSTEM },
  "thermostat": { THERMOSTAT },
  "airSealing": { AIR_SEALING },
  "atticInsulation": { ATTIC_INSULATION }
}

Operate on existing systems

Remove or adjust relevant values of existing systems (e.g. heating, cooling, heat pump, water heater or distribution systems). The defaulting engine determines whether a house contains one or more of these systems. Existing systems are harder to refer to in improved building definitions and assumptions change from house to house. For that reason, these automated measures help modify the base building definition without much knowledge of said characteristics.

Existing HVAC Heating System

Operations to the existing HVAC heating system are entered in automatedMeasures.existingHvacHeatingSystem. This object covers the singular predefined system providing heating in the base building, including a heat pump.

{
  "action": "adjust",
  "adjust": {
    "heatLoadFraction": 0.2,
    "backup": true
  },
  "costs": [ COST ]
}

The following table specifies the schema for the existingHvacHeatingSystem object.

Property	Type	Constraints	Required	Description
action	String	See [48]	Yes	Operation on existing heating system
adjust	Object		No [49]	System properties to adjust
costs	Array of Cost		No [50]	Implied costs of measure

[48]

action choices are “keep”, “remove”, or “adjust”.

“keep” maintains existing heating system as is, including load fraction. Using this action indicates that there are no changes to heating at all. This action will override anything in adjust object.

“remove” indicates the existing heating system is completely removed. New system(s) must cover 100% of load or specify heatLoadGapFraction. This action will override anything in adjust object.

[49]

The adjust object is required if action is set to adjust.

[50]

Defaults to [] if not provided.

Note

If action = “remove” and the existing water heating system is dependent on the removed heating system (i.e. indirect water heater), then a new standalone heat pump water heating system will automatically be added to the improvedBuilding.

Note

If action = “remove” and the existing heating system is a heat pump, then the existing cooling system will also be removed. This is based on the assumption that the newHeatPump will serve both loads.

adjust schema for existing HVAC heating system:

Property	Type	Constraints	Required	Description
backup	Boolean		See [51]	Indicates the existing heating system is being kept, but switched to be a backup system
heatLoadFraction	Double	0 - 1	See [51]	Heat load for the existing heating system

[51] (1,2)

Either backup or heatLoadFraction can be defined. If backup is true, then heatLoadFraction must be 0 or undefined. If backup is false, then ``heatLoadFraction must be > 0.

Existing HVAC Cooling System

Operations on the existing cooling systems are entered in automatedMeasures.existingHvacCoolingSystem. This object covers the singular predefined system providing cooling in the base building, including a heat pump.

{
  "action": "adjust",
  "adjust": {
    "coolLoadFraction": 0.2
  },
  "costs": [ COST ]
}

The following table specifies the schema for the existingHvacCoolingSystem object.

Property	Type	Constraints	Required	Description
action	String	See [52]	Yes	Operation on existing cooling system
adjust	Object		No [53]	System properties to adjust
costs	Array of Cost		No [54]	Implied costs of measure

[52]

action choices are “keep”, “remove”, or “adjust”.

“keep” maintains existing cooling system as is, including load fraction. Using this action indicates that there are no changes to cooling at all. This action will override anything in adjust object.

“remove” indicates the existing cooling system is completely removed. New system(s) must cover 100% of load or specify coolLoadGapFraction. This action will override anything in adjust object.

[53]

The adjust object is required if action is set to adjust.

[54]

Defaults to [] if not provided.

Note

If action = “remove” and the existing cooling system is a heat pump, then the existing heating system will also be removed. This is based on the assumption that the newHeatPump will serve both loads.

adjust schema for existing HVAC cooling system:

Property	Type	Constraints	Required	Description
coolLoadFraction	Double	0 - 1	Yes	Cool load for the existing cooling system

Existing HVAC Distribution System

Operations on the existing distribution systems are entered in automatedMeasures.existingHvacDistributionSystem. This object covers the predefined distribution system(s), either air and/or hydronic, connected to the base building’s heating and cooling systems.

{
  "action": "adjust",
  "adjust": {
    "leakageValue": 0.1,
    "insulationRValue": 5
  },
  "costs": [ COST ]
}

The following table specifies the schema for the existingHvacDistributionSystem object.

Property	Type	Constraints	Required	Description
action	String	See [55]	Yes	Operation on existing distribution system
adjust	Object		No [56]	System properties to adjust
costs	Array of Cost		No [57]	Implied costs of measure

[55]

action choices are “keep”, “remove”, or “adjust”.

“keep” maintains existing distribution system as is. Using this action indicates that there are no changes to the distribution system at all. This action will override anything in adjust object.

“remove” indicates the existing distribution system is completely removed. This action will override anything in adjust object.

[56]

The adjust object is required if action is set to adjust.

[57]

Defaults to [] if not provided.

adjust schema for existing HVAC distribution system:

Property	Type	Constraints	Description
leakageUnits	String	See [58]	Duct leakage units must be the same as baseBuilding.
leakageValue	Double	>= 0.0	Duct leakage value
insulationRValue	Double	>= 0.0

Values can be defined and will only be applied if applicable. For example, if there isn’t airDistribution, then leakageValue won’t be applied.

[58]

Units choices are “CFM25”, “CFM50”, or “fraction”.

Existing Water Heating System

Operations on the existing water heating system can be entered in automatedMeasures.existingWaterHeatingSystem. This object covers the predefined water heating system in the base building.

{
  "action": "adjust",
  "adjust": {
    "dhwLoadFraction": 0.8
  },
  "costs": [ COST ]
}

The following table specifies the schema for the existingWaterHeatingSystem object.

Property	Type	Constraints	Required	Description
action	String	See [59]	Yes	Operation on existing water heating system
adjust	Object		No [60]	System properties to adjust
costs	Array of Cost		No [61]	Implied costs of measure

[59]

action choices are “keep”, “remove”, or “adjust”.

“keep” maintains existing water heating system as is, including load fraction. Using this action indicates that there are no changes to the water heating system at all. This action will override anything in adjust object.

“remove” indicates the existing water heating system is completely removed. This action will override anything in adjust object.

[60]

The adjust object is required if action is set to adjust.

[61]

Defaults to [] if not provided.

adjust schema for existing water heating system:

Property	Type	Constraints	Description
dhwLoadFraction	Double	0 - 1	Domestic hot water load for the existing water heating system

Add new systems with minimal configuration

Adding a new system may require knowledge of the current house, possibly not available at request time. For that reason, simpler instructions are made available to let the user add a system with minimal configuration (e.g. ENERGY STAR compliant heat pump).

New Heat Pump

Characteristics of a new heat pump system can be entered in automatedMeasures.newHeatPump.

{
  "systemType": "heat pump",
  "performanceClass": "energy star compliant",
  "heatLoadFraction": 0.8,
  "coolLoadFraction": 0.8,
  "costs": [ COST ]
}

The following table specifies the schema for the newHeatPump object.

Property	Type	Constraints	Required	Default	Description
systemType	String	See [62]	Yes		Type of heat pump
performanceClass	String	See [63]	Yes
heatLoadFraction	Double	0 - 1	Yes		Heat load for the new heat pump
heatLoadGapFraction	Double	0 - 1	No	0.0	Heat load for the new heat pump
coolLoadFraction	Double	0 - 1	Yes		Cool load for the new heat pump
coolLoadGapFraction	Double	0 - 1	No	0.0	Cool load for the new heat pump
costs	Array of Cost		No	[]	Implied costs of measure

[62]

systemType choices are “heat pump”, “mini-split” or “air-to-air”

“heat pump” is a generic air source heat pump that will be automatically determined based on the existing conditions in the building. If the existing building contains ducts, a central ducted ASHP will be defined. If no ducts exist, a ductless mini-split will be defined.

[63]

performanceClass choices are “federal minimally compliant” or “energy star compliant”

Assumptions for efficiencyClass:

Type	Federal Minimally Compliant	ENERGY STAR Compliant
mini-split (ductless)	SEER: 14, HSPF: 8.8	SEER: 17.8, HSPF: 10
air-to-air (ducted/central)	SEER: 14, HSPF: 8.8	SEER: 15.7, HSPF: 9.2

New Water Heating System

Characteristics of a new water heating system can be entered in automatedMeasures.newWaterHeatingSystem.

{
  "systemType": "storage water heater",
  "efficiencyClass": "premium",
  "dhwLoadFraction": 1.0,
  "costs": [ COST ]
}

The following table specifies the schema for the newWaterHeatingSystem object.

Property	Type	Constraints	Required	Default	Description
systemType	String	See [64]	Yes		Type of water heating system. fuelType assumed as base heating fuel for “storage water heater” and “instantaneous water heater”.
efficiencyClass	String	See [65]	Yes
dhwLoadFraction	Double	0 - 1 [66]	No	1.0	DHW load for the new water heating system
costs	Array of Cost		No	[]	Implied costs of measure

[64]

systemType choices are “storage water heater”, “instantaneous water heater”, and “heat pump water heater”

[65]

efficiencyClass choices are “standard” or “premium”

[66]

The sum of dhwLoadFraction across all water heating systems must be <= 1.

Assumptions for efficiencyClass:

Type	Fuel	Standard	Premium
heat pump water heater	electricity	N/A	3.5
storage water heater	electricity	0.92	0.95
storage water heater	natural gas	0.59	0.67
storage water heater	fuel oil	0.62	0.68
storage water heater	propane	0.59	0.67
storage water heater	other	0.59	N/A
instantaneous water heater [20]	electricity	0.99	N/A
instantaneous water heater [20]	natural gas	0.82	N/A
instantaneous water heater [20]	fuel oil	N/A	N/A
instantaneous water heater [20]	propane	0.82	N/A
instantaneous water heater [20]	other	N/A	N/A

[20] (1,2,3,4,5)

performanceAdjustment of 0.92 will be applied to instantaneous water heaters to account for cycling.

Adjust global aspects of the building

Use these special measures to adjust global aspect of the building. At the moment, the supported measures modify the thermostat, attic insulation and air sealing.

Air Sealing

Adjustments to the building air leakage rates can be entered in automatedMeasures.airSealing.

{
  "adjust": {
    "rate": 1.0
  },
  "costs": [ COST ]
}

The following table specifies the schema for the airSealing object.

Property	Type	Required	Description
adjust	Object	Yes	Aspect properties to adjust
costs	Array of Cost	No [67]	Implied costs of measure

[67]

Defaults to [] if not provided.

adjust schema for air sealing:

Property	Type	Constraints	Default	Description
rateUnit	String	See [68]	ACH	Units of air leakage rate
rate	Double	> 0.0	7.0	Value of air leakage rate
housePressurePa	Double	> 0.0	50.0	House pressure in Pa with respect to outside

[68]

rateUnit choices are ACH or CFM.

Attic Insulation

Adjustments to existing attic insulation can be entered in automatedMeasures.atticInsulation.

{
  "adjust": {
    "floorAssemblyEffectiveRValue": 50.6
  },
  "costs": [ COST ]
}

The following table specifies the schema for the atticInsulation object.

Property	Type	Required	Description
adjust	Object	Yes	Aspect properties to adjust
costs	Array of Cost	No [69]	Implied costs of measure

[69]

Defaults to [] if not provided.

adjust schema for attic insulation:

Property	Type	Units	Constraints	Default	Description
floorAssemblyEffectiveRValue	Double	F-ft2-hr/Btu	> 0.0	50.6	Effective R-value of attic floor assembly

Thermostat

Adjustments to thermostat settings can be entered in automatedMeasures.thermostat.

{
  "adjust": {
    "heatingSeason": {
      "setpoint": 68,
      "setback": 64,
      "setbackStartHour": 23,
      "totalWeeklySetbackHours": 49,
    },
    "coolingSeason": {
      "setpoint": 78,
      "setback": 82,
      "setbackStartHour": 9,
      "totalWeeklySetbackHours": 42,
    },
  },
  "costs": [ COST ]
}

The following table specifies the schema for the thermostat object.

Property	Type	Required	Description
adjust	Object	Yes	Aspect properties to adjust
costs	Array of Cost	No [70]	Implied costs of measure

[70]

Defaults to [] if not provided.

adjust schema for thermostat:

Property	Type	Description
heatingSeason	Object	Thermostat settings for heating season
coolingSeason	Object	Thermostat settings for cooling season

heatingSeason and coolingSeason objects share the following schema:

Property	Type	Units	Constraints	Default	Description
setpoint	Integer	F	> 0	Heating: 67, Cooling: 78	Season setpoint temperature
setback	Integer	F	> 0	Heating: 64, Cooling: 72	Season setback temperature [71]
setbackStartHour	Integer		0 - 23	Heating: 23, Cooling: 9	Start hour for daily setback period
totalWeeklySetbackHours	Integer	hrs/week	> 0	Heating: 49, Cooling: 42	Hours per week of temperature setback

[71]

Also referred to as setup temperature for the cooling season.

Cost

{
  "label": "Main Cost", //optional
  "loanId": "Loan1",
  "incentiveIds": [ "Incentive1", "Incentive2" ],
  "costType": "one time", // ("one time" | "recurring")
  "recurrencePeriod": 30, //number of days //required if costType is recurring
  "fixedCost": 10,
  "variableCost": VARIABLE_COST //not currently supported
  "userData": {
    "sku": "123"
  },
}

Custom Measures

// CUSTOM_MEASURE
{
  "label": "kitchen counter replacement",
  "description": "replace laminate counters with marble",
  "costs": [ COST ], // refer to the Cost schema
}

Improved Building

Custom-defined improved buildings are not currently supported. The associated schemas will be added here in a future version.

Global Controls

Global controls is an optional schema and contains a variety of customization settings that affect all models contained within the request.

// GLOBAL_CONTROLS
{
  "debug": true,  // defaults to false, provide all the debugging info for development and integration

  "includeInputs": true, // defaults to true, mirror user inputs in the response

  "includeEnergyEndUses": false, // defaults to false

  "includeDefaultAssumptions": false, // defaults to false

  "includeBaseResults": true, // defaults to true

  "includeTypical": false, // defaults to false

  "useFixture": false, // defaults to false

  "fixtureName": "automated-measures-new-heat-pump", // fixture to use (required if useFixture is true)

  // Instruct which financial calculations will be included in the response.
  // If not provided, the default values are "difference", "installationCosts" and "energyCosts".
  // To return no financial analysis altogether, pass in an empty array ([]).
  //
  "financialAnalysisOptions": ["difference", "installedCosts", "energyCosts"], // ("ROI" | "cashflow" | "SIR" | "MIRR" | "difference" | "installedCosts" | "energyCosts")

  // Energy, costs and emissions data resolution.
  // If not provided, the default value is only "annual".
  //
  "resolution": ["annual", "monthly"], // ("hourly" | "monthly" | "annual") //defaults to annual

  "includeStatusQuoTimeline": false, // defaults to false

  // Anchor timelines and models to a start date.
  // * Date value is in the YYYY-MM-DD format
  // * Date value can be set in the past.
  // * All models' "appliedOn" dates must happen after this value.
  // * If not provided, the default value is the current date.
  //
  "timelineStartDate": "2022-12-15",

  // Length of the timelines in years. Used to compute costs, differences and the financial analysis.
  // If not provided, the default value is 1 year.
  //
  "timelineDurationInYears": 1,

  "units": UNITS, // optional, refer to the Units schema

  "escalationRates": ESCALATION_RATES, // optional, refer to the Escalation Rates schema
}

Units

Units is an optional schema that allows the user to specify what unit(s) are included in the response.

// UNITS
{
  "energyStandard": "MBtu", // ("MBtu")
  "coal": "metric ton",     // ("MBtu" | "short ton" | "metric ton")
  "electricity": "kWh",     // ("MBtu" | "kWh")
  "fuelOil": "gallon",      // ("MBtu" | "gallon")
  "naturalGas": "ccf",      // ("MBtu" | "therm" | "ccf")
  "propane": "gallon",      // ("MBtu" | "gallon")
  "woodCord": "MBtu",       // ("MBtu")
  "woodPellets": "MBtu",    // ("MBtu")
  "monetary": "USD",        // ("USD")
  "emissions": "CO2"        // ("CO2")
}

The following list contains the conversion factors used within the modeling engine.

• 1 MBTU= 1,000,000 BTU

• 1 BTU = 0.000293071 kWh

• 1 BTU = 1.055056 × \(10^{-5}\) therms

• 1 kWh = 3412.142 BTU

• 1 kWh = 0.003412142 MBTU

• 1 metric ton of coal = 20.9 MBTU

• 1 short ton of coal = 19.6 MBTU

• 1 gallon fueloil = 0.139 MBTU

• 1 gallon propane = 0.09154 MBTU

• 1 ccf natural gas = 1.034129 MBTU

• 1 therm natural gas = 0.000010015 MBTU

Escalation Rates

// ESCALATION_RATES
{
  "electricity": [1.0, ..., 1.0],
  "naturalGas": [1.0, ..., 1.0],
  "equipmentUpgrades": [1.0, ..., 1.0]
}